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PREFACE 


This manual is an introduction to Perkin-Elmer 32-bit software 
Products and includes an overall description of task traps, 
macros, and file management. The manual is inteniei for 
application level programmers designing and programming tasks to 
run under 0S/32. 


Chapter 1 is an overall description of Parkin-Elm2r 32-bit 


software products used for program preparation. chapter 2 
describes the task structures. Chapter 3 presents traps and 
details trap-causing events. Chapter 4 presents system mastros 


and data structures. Chapter 5 contains information on volume 
organization, file types, classes, and file management methods. 


This manual has been extracted from the obsolete OS/32 Programmer 
Reference Manual, Publication Number S29-613. This manual 
applies to the 0S/32 R96 software release and higher. 


The following manuals can be used in conjuncstion with this 
manuals 


PUBLICATION 


MANUAL NAME Fe NUMBER 
OS/32 AIDS User's Guide $29-374 
BASIC Level II Reference Manual $29-488 
OS/32 Bit é pheonade Communications Reference 
Manual S29-544 
COBOL Reference Manual S29-545 
CORAL 66 Reference Manual 529-587 
Source Updater User Guide | | S29-630 
FORTRAN VII D User Manual S$29-657 
FORTRAN VII O User Manual 5329-3659 
RPG II Reference Manual 529-661 
OS/32 COPY User Guide | 5329-676 
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PUBLICATION 


MANUAL NAME | NUMBER 
O0S/32 TEXT User Guide 529-677 
0S/32 Link Reference Manual 48-0905 
0S/32 Edit User Guide 48-008 


32-Bit Systems User Documentation Summary 50-003 


Pascal User Guide, Language Reference, and Run 


Time Support Reference Manual > 48-021 
OS/32 System Planning and Configuration Guide 48-024 
OS/32 Operator Reference Manual 48-030 
System Generation (SYSGEN/32) Reference Manual 48-037 
0S/32 System Level Programmer Reference Manual 48-040 
OS/32 Multi-Terminal Monitor (MTM) Reference 

Manual 48-043 
Common Assembly Language/32 (CAL/32) Programming 

Reference Manual © 48-050 
CAL Macro/32 Processor and Macro Library Utility 


Reference Manual 48-057 


For further information on the contents of all Parkin-Elner 
32-Bit manuals, see the 32-Bit Systems User Documentation 
Summary. 
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CHAPTER 1 
PERKIN-ELMER OS/32 PROGRAMMING LANGUAGES AND UTILITIES 


401 INTRODUCTION 


This chapter provides an overview of the programming languages 
and utilities available for program development under the 0S$/32 
and MIM environments. The Reliance environment is also available 
for transaction processing. 


71-2 ENVIRONMENTS 


Pregrams can be develcped under the basic O0S/32 environment or 
the multi-terminal monitor (MTM) environment. Programs developed 
in an OS/32 environment can be entered only at the system 
console. Programs developed in an MIM environment can be entered 
at any available terminal. MTM is an OS/32 extension that allows 
time sliced interactive programming and batch programming. If 3 
system is configured to include tne Reliance extension in 
addition to MIM, programs cannot be developed while running unier 
Reliance. The terminal user, however, can Switch from. Reliance 
to the MTM environment by using the environment control monitor 
(ECM). If programs are then developed in the MIM environment, 
they cannot be added to the Reliance system unless tha Reliance 
system is completely shut down. For further jletails concerning 
the use of the ECM, see the Environment Control Monitor (ECH) 
Reference Manual. 


12-3 PERKIN-ELMER OS/32 PROGRAMMING LANGUAGES 


The following nine languages are supported by 29S/32: 


® Common Assembly Languag2/32 (CAL/32) 
e CAL Macro/32 

® FORTRAN VII Development (D) Compiler. 
e FORTRAN VII Optimizing (0) Compiler 
e@ COBOL 


@ BASIC Level II. 
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© CORAL 66 
© RPG II 


e® Pascal 


1.3.1 Common Assembly Language/32 (CAL/32) 

CAL/32 produces the Perkin-Elmer 32-bit object code format from 
source code input. Features include: 

e Program relocation 

@® Program segmentation 

e Complex data definitions 

® Expression analysis 

® Code optimization 


e Conditional assembly instructions 


1-3.2 CAL Macro/32 


CAL Macro/32 allows programmers to define macros for .use in 
program generation. A macro is a copy of a frequantly used 
assembler code sequence that is inserted into a macro library. 
A macro call or request is made to the library to insert a macro 
into the body of the calling task. Once inserted, the macro is 
expanded by the CAL Macro/32 processor into internediate source 
Statemants that CAL/32 can convert into object code for 
processing with the rest of the task. Features incluie: 


® Ability to process both user-defined and Perkin-Elmer supplied 
macros 

® Positional, keyword, or mixed mode macro prototype statements 

e Nested macro instructions 


e Conditional macro expansion independent of coniitional 
assembler instructions 


e Ability to incorporate variables within a macro definition 
e® Macro call instructions for calling frequently used macro 
definitions into memory at the Start of macro processor 


execution 


® Macro trace facility 
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1.3.3 FORTRAN VII Development (D) Compiler 

The Perkin-Elmer FORTRAN VII Development (D) Compiler passes 
through the source program only once to proiuce objezt coda in 
32-bit format. Features include: 

@ Over 100 compile time diagnostic routines 


® Run tine error messages 


e Optional run time debug facility for eneekias subscript ya tues 
and tracing variables and labeled statements 


® Conditional compilation for diagnostic programming 


1.3.4 FORTRAN VII Optimizing (0) Compiler 

FORTRAN VII O is designed to minimize user program execution tine 

by producing object cole in 32-bit loader format or CAL/32 source 

format. When global optimization is enabled, program flow and 

language constructs are analyzed at the source program level, 

reducing the number of computations required at execution. 

Features include: | 

® Diagnostic compilation routines (250) 

e Run time error messages 

® Optional run time debug facility for checking subscript values 

@ Optional trace facility for variables and labeled statements 

e Conditional compilation for diagnostic programming 

e Batch compilation facility for compiling several subprograms 
using 2 single compiler invocation 

12.3.5 COBOL 

The COBOL compiler processes COBOL source statements td =produce 

CAL/322 source statements that are assembled by CAL/32 into object 

Erograms. Functions include: 

e@ Sequential I/0 

e® Relative I/0 

@® Indexed I/0 


° Interprogram communication 
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e Table handling 
e Sort 
e Debug 


e Library functions 


4.3.6 BASIC Level II. 

The BASIC Level II Interpreter allows users to. create, execute, 
and modify programs interactively. Features include: 
® Single/double precision floating point 

e ASCII and binary I/) | 

° File and device access 

® Program and matrix manipulation 

e String operations 

e “‘Heersaerinea functions. 

e Tracing 

e Programmed error handling 


® Syntax error checking 


1.3.7 CORAL 66 

CORAL 66 is a high level language primarily designed for 
implementing online real time systems. Perkin-Elmer CORAL 56, 
which is based on Algol 60, incorporates features of FORTRAN and 
Jovial. Major features offered by the compiler include: 

@ Block structure 

e Algol-like procedures 

e Independent compilation 

® Code inserts 

® kKuilt-in macro scheme 

@© Mixed arithmetic 


e@ Library functions 


@ Packed data format 
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153.8 Report Program Generator (RPG II) 


RPG II is a high level language primarily designed for file 
updating and report generation. RPG II provides seven 
preformatted forms used to code programs to input, process, and 
retrieve data files. Sequential, relative, ani indexed files can 
be accessed randomly or sequentially. Perkin-Elmer RPG II also 
can be used to process online files maintained by the 
Perkin-Elmer database system, Data Management System/32 (DM5/32). 


1.3.9 Pascal 


The Pascal compiler provides a set of control statements for 


Manipulating data structures. Pascal has many standari data 
types available such as Boolean,’ character, or real. Tha 
programmer can also define data structures that are more 


appropriate abstractions of the problem data and combine sinple 
data structures into arrays and records. 


Pascal automatically expands all integer variable values within 
an arithmetic expression to the length of the longest operani. 
In addition, all literal integer constants within an arithmetic 
expression are compiled as type INTEGER, while all literal real 
constants are compiled as type REAL. 


A variety of executable statements is available to the Pascal 


programmere | Simple statements, such as the Empty, Assignment, 
Procedure Call, and the GOTO statements, perform one specific 
operation. Structured statements are a combination of other 


statements such as the compound statement that provides a 
framework for the . main body of a program. The Pascal CASE 
Statement is a structured statement that provilies the sapability 
of the computed GOTO of FORTRAN but does not require statemant 
labels. Because the alternatives to be executed under each 
condition are embedded in the CASE statement structure, this 
statement reduces the need of GOTO statements in a program. 

The Perkin-Elmer implementation of Pascal, which is a subset of 
the standard defined in the Pascal User Manual and Report by 
Jensen and Wirth, features: 

® Syntax graphs 

e Header statements 

® Run time supvort 


© Command substitution system (CSS) procedures 


ce OR ey tS OD EE een Om) a Om oe Gm ey Ee OH Se Oe eR am om WP er ee ow mm oe op 


Springer-Verlag, 1975. 
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1-4 UTILITIES 

The following Perkin-Elmer abies, prograns can be used with 
OS/32: 

® Linkage Editors 

® Edit 

e Text 

e® Source Updater 

® Automatic Interactive Debugging Systen (AIDS) 
e Copy | | | 

e Library Loader 

e Macro Library 

e Sort/Merge agen II 


® Patch 


1-4%.1 Linkage Editors 


Perkin-Flmer Linkage editors are used to generate an image load 
module from one or more object modules. Image load modules can 
be tasks, sharable segmentsS, or operating systems. External 
references to task common and to previously established reentrant 
library segments are also processed. The available linkage 
editors are: a 


® Link 


® TET 
Link replaces TET under OS/32 R06 and higher. 


424.1401 Link 


Perkin-Elmer Link can build image load modules in sizes up to 
16Mb. The Link tree-structured overjJay feature allows automatic 
loading of user-specified routines into an overlay area when the 
routine is called during task execution. The overlay structure 
does not have to be defined in the source module. 
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1.4.1.2 Task Establisher Task (TET) 

Each TET overlay must be defined completely before another 
overlay statement is presented in the command strean. After all 
overlays are defined, the task overlay area is set to the size of 


the largest area requested. Only one overlay area is reserved 
for each task, no matter how many overlay commands are entered. 


Edit is a disk-based editor that can be used to append, alter, or 

save data on a line-by-line basis. Features includes 

® Interactive or batch mode suleeatiea: 

@ Global alterations of character strings 

e Data deletions, additions, or insertions 

e® Character string searches 

e Permanent file data storage 

e User-specified record length, termination characters, and tab 
settings 

1-4.3 Text 

Text is used to generate, revise, and print manuals, iocuments, 

and letters. The editor is linked with Text to provide all 

editing capabilities. Text features include: 

@® Line centering 

® Margin definition 

e Boldface entries 

® Pagination 

® Right justification 

e Left justification 

® Underscoring 


e@ Indention 
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124.4 source Updater 


The Source Updater is used to create and maintain source files 


mass storage devices. Source updater commands enable the user 


verify, modify, or list source files. 


124.5 - Automatic Interactive Debugging System (AIDS) 


AIDS is a user-oriented assembly level debugging program that: 


Displays and modifies memory locations and floating point 
general registers 


Prints sections of memory to a list device 


Provides the following program utilities: 


- Snapshot printouts 
- Cell/register protection 
- Trace execution 


- Breakpointing 
Provides single step execution that displays: 


- Current bias 

ai Location counter 
- Task status 

- Condition code 


Converts reguested data or the current open cell from 
format to another 


1-426 Copy 


Copy transfers data from one device to another davice 
supports: 


on 
to 


and 


one 


and 


A verify operation that guarantees the integrity of copied 


data 


Blocked or unblocked, labeled or unlabeled input and output 


tapes 
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1.4.7 Library Loader 

Library Loader is an interactive utility that allows the operator 
to create object program library files on a mass storage device. 
Once the object program library files ars created, operator 
commands can be used to search these files. In addition, the 
automatic link editing feature allows the operator to load all 
library programs required for any one particular task by using 
only one command. 

1.4.8 Macro Library 

The Perkin-Elmer Macro Library Utility Program provides 
capabilities for establishing and maintaining the system macro 
library and/or any user-designated. macro libraries. This 
utility: 

e Creates a new library 

® Maintains an existing library 

® Adds new macro definitions to a library 

e Deletes macro definitions from a library 


e Lists macro definitions from a library to 2 davice file 


e Prints the directory macro names of a library to a device or 
file 


® Stores an uplated library in a permanent file 


1.4.9 Sort/Merge Level II 


Sort/Merge Level II allows a user to reorder a file of fixed 
length records according to user-defined key fields; or projuce 
a Single, ordered file from two or more input files of fixed 
length records that presorted in identical key sequences. [he 
main features of Sort/Merge Level II are: 


e Input and output can use disk, magnetic tape, or any 
sequential, fixed length record device. 
e® Commands and parameters can be input on an interactive device. 


e As many key fields as required can be specified (up to a 
Maximum total key length of 1024 bytes). 
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e Keys can be of a variety of types: 


~- String 

- Signed binary integer (16-, 32-, and 64-bit) 
- Signed floating point binary (32- and 64-bit) 
~- Packed decimal 

- Unpackedi decimal 


e Ascending or descending sequence can be spacified separately 
for each key. . 
e Up to four files can be merged. 


e® A single input file can be specified to thea merge function, 
providing a record sequence checking facility. 


®e A series of input files can be sorted together as an 
alternative to a sequence of separate sorts followel by marga 
operations. 

® Repeated sort and/or merge opéerations can be carried out 
without reloading the progran. 

712-4210 Patch 

Patch is -a program development tool that allows users t> aid to 

or change object or image program versions witnout reassembling 

the source module. The capabilities provided are: 

e A history feature that records all changes made 

_® The ability to manipulate object libraries and compound 


overlay files 


Patch is a disk-based reentrant program that can run in eaither 
interactive or batch mode. 
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CHAPTER 2 
TASK STRUCTURE 


2-1 INTRODUCTION 


The fundamental work unit of the Perkin-Elmer 32-bit operating 
system is the task. A task can be a single program or a main 
program with a number of subroutines and overlays. A total of 
252 tasks can reside in the system at one time. 


Each task is compiled or assembled into an object code module. 
From this object module, Link builds an image load module. Ince 
the image load module is built, the task can b2 loadei using 4a 
LOAD command or a load function executed by another task. Tasks 
are identitied by a taskid assigned to the task when it is loaded 
into the system. A group of special program davelopment commanis 
are available to facilitate compiling, linking, anid running of 
tasks. These commanis are described in detail in the 035/32 
Multi-terminal Monitor (MTM) Reference Manual. 


This’ chapter discusses. task structure as defined by 08/32. 
Included are explanations of task address space, task segments, 
task states, and subtasking. 


2.2 TASK AND MEMORY PROTECTION 


User tasks (u-task) run in a protected node. They cannot be 
accessed by tasks outside their boundaries. In addition, u-tasks 
cannot execute code in common areas or use any of the privileged 
instructions. The privileged instructions include all Ifo. 
instructions; e.g.-, O9C, RH, WH, SSR, and any instruttion that 
changes the state of the processor, such as LPSWR or EPSR. 


To execute I/0 instructions or change the processor state, 
u-tasks make requests of the operating system via a supervisor 
call (SVC) instruction. The relocation/protection hardware 
provides memory protection for u~taskse Ihe 


relocation/protection hardware and the Perkin-Elmer processors 
associated with it are: 


e Memory access controller (MAC) 


- Model 7/32 
- Model 8/32 


- Model 3220 
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@ Memory address translator (MAT) 


~ Model 3210 
- Model 3230 
- Model 3240 


~-~ Model 3250 


This protection is transparent to u-tasks running under 05/32. 


Task memory access errors are handled automatically by the 
Operating system or by the task itself if a trap service routine 
exists. 


2-3 USER TASK (U-TASK) ADDRESS SPACE 


When a uctask is loaded into memory, relocation/protection 
hardware automatically relocates the. task relative address to 
physical memory. The u-task refers to data and instructions 
relative to the first location in the task as if the task were 
loaded at location 0 in memory. 


U-task address space is divided into segments. A segmant is a4 
set of contiguous program addresses Starting on a 64kb boundary. 
A maximum of 16 segments on a MAC machine is available for each 
u-tasck. Each seqment is divided into 256-byte pagese See Figure 
2716 , 


15 | | 

S  atatatetatatedetetaatatetatetetatatetetetatatetetatsatatetanans | F0000 
14 | | 

E atetatatatatataatstahadatatetatatatataaatatatataatatatate | 
13 


4 | 1IMb 
E | rm rt re er wr ee ee ere e een er enen | 
3 | | 
N [pester tere eres eee es | 
2 | { 
T eeteiaa a cuicaiiaeice cea eeiear eas | 
a. : 
0 | { 256 256-byta 


a aa ca od - pages or 64kb , 


Figure 2-1 Task Address Space on a Memory Access 
Controller (MAC) Machine 
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On MAT machines a maximum of 192 Segments are available for each 
u-task, and each of these segments is divided into 2048-byte 
pages. See Figure 2-2. 


oe ee ee em ae ow wwe a Te ee ee ee om we a OF om Ow om OF 68 GS Ge @ we em ow a a oF ot 


191 | | 
: |---------------- wt ee een ene |} BFOOOO 
S 190 | | 
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E 189 | | 
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G 188 | | 
: u | | | | 12Mb 
[Sees ees SSeS e ee see SH S445 see SSeee= | 
N 3 | | 
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T 2°. ° | 
Pan se Sre Stare ee eee sta ee | 
S 1 | 7 | 
[SSSss Reese se seeSe aes eee =| 
Oo | {| 32 2048-byte 
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Figure 2-2 Task Address Space on a Memory Address Translator 
(MAT) Machine 


The task address of each segment begins on a Segment boundary; 
@eGe, 00000, 10000, 20000, up to FOO000 (1Mb) for MAC machines, 
and up to BFOO0OO (12Mb) for MAT machines. 


2-4 TASK SEGMENT TYPES 


Segments within u-task address space are classified as pure or 
impure. An impure segment can be written to, reai from, or 
executed only by the task in which it resides. A pure Segment 
contains data or instructions that can be read or executed by any 
task. In addition, a u-task can contain one or mor2 optional 
reentrant library segmants or common data areas. 


2e-4.1 Impure Segments 


Every task must have an impure segment to hold the user program 
and data. This segment, which cannot be shared with any other 
u-task, starts with segment number O. If tha u-task occupies 
more than the 64kb of address space, the task is extandei into 
One or more of the segments contiguous to the first impure 
segment. ; ; 
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The impure segment is defined by three parameters: UBDT, UTIOP, 


and CTOP. The current values of these three parameters are 
available to the terminal user through the DISPLAY PARAMETERS 
command. UBOT always halds the starting adiress of the impure 


segment. For u-tasks this address is always Y'O'. 


When a task is loaded, UTOP holds the address of the first 
fullword above the defined portion of the impure segnent. Tha 
defined portion is the section of the impure segment that is 
explicitly defined in object code by Link. Some programs use an 
undefined portion of memory above their defined portion for 
dynamic storage. An example of such an undefined area is the 
symbol table area used by Common Assembly Language/32 (CAL/32). 
While this undefined area lies within the impure segmant, it lias 
above the area to which UTOP points but below the area defined by. 
CTOP, the address of the highest halfword in the impure segment. 
For a MAC machine, CIOP always contains an address that is o929ne 
halfword less than a 256-byte boundary. For a MAT machine, CIOP 
always contains an address that is one halfword less than a 
2048-byte (2kb) boundary. See Figure 2-3. 


| lop ¢---crop 
| Undefined portion { 
of impure sagment | 


ULOReS 21a | 
a ea | 
| 
| Defined portion | 
| of impure segment | 
| 
peso das nee es acetanessaaes ee eses | 
| | 

UDL | 
| 


Figure 2-3 Impure Segment 
Link defines the initial values for UTOP and CIOP when the u-task 
is built. Link increases the value of CTOP through the commani: 
OPTION WORK=(min,max) 


This command gives the task an undefined storage area above its 
originally defined space. Using the LOAD command can increase 
the value of CTOP at load time. After a task is loaded, the 
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value of UTOP can be modified by a GETSTORE ani a RELSIORE macro. 
When a reSident task is restarted, the original value vf UIOP is 
restored. 


If a program uses overlays, the overlay area becomes a part of 
the impure Segment. UTOP initially is set equal to the address 
of the first fullword above the overlay area. The overlay area 
is large enough to contain the largest program overlay. During 
task execution, the overlay area will have only one resident 
overlay. Thus, in memory, the impure segment of a task using 
overlays contains (beginning at the lowest. location) a root 
section, an overlay section, and an expansion section (if usei). 
Any expansion area follows the overlay area. See Figure 2-4, 


| |__| ¢---crop 
| | 
| Expansion area | ‘Undefined portion 
| | of impure segment 
UTOP <> [moons . : I) 
dan tan | 
| , | 
| Overlay area | 
L | 
| ee nn rr ree | Defined portion _ 
| . | of impure segment 
| Root section | 
| | | 
[pape ti ganecsaagessrSasseee sear sees | 
| | 
| UDL | 
I 


Figure 2-4 Impure Segment with Root and Overlay Area 


The task code in the task impure segment is preceded by the user 
dedicated location (UDL) that occupies memory locations 90 through 
255. The UDL contains task status word (TSW) swap areas used for 
communication between the operating system and the task. 


2-4.2 Pure Segments 


The user can optionally allocate one pure Segmant within a task. 
This segment is the shared portion of the task ani uses the 
lowest available segment after the maximum workspace § size 
reserved by Linke The actual segment number used is computel by 
Link. The size of the pure segment is limited only by the total 
number of segments within a taske The pure segment contains 
reentrant code that can be shared by several tasks conzturrently. 
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The code for this segment is assembled with the CAL/32 option 
PURE. A task cannot modify any location within its pure segment. 
The relocation/protection hardware prevents other tasks fron 
‘writing to the pure segments. 


The Link command: 
OPTION WORK=(min, max) 


builds the pure segment above the maximum workspace area. 
See Figure 2-5. 


2 we we ey ee ee ew ee ae owe oe om oe om ae oe om of oe om os oe OD an oe oe Ot oe ow oe 


[sgateaee reser senarer secon aan | 
| Maximum workspace 
| Size specified by 

{ |). Link 

t 

Pe ont american serena 

| : --|<---CTOP 

| 

UTOP--->|---~-| | 

(seg epee eee nen ! 

| | 

| Defined portion of { 

| impure segment | 

| { 

[aoe eee eae ara tesa | 

| | 

| UDL | 

UBOT---> |---| | 


— oe ee ee ee ee ee et eee es ee ee ee ee ow ee ee we em oe oe oe 


Figure 2-5 Pure Segment 


2-5 IMAGE LIBRARIES 


Image libraries are segments built by Link outside the u-task 
address space. An example is the FORTRAN run time library (RIL). 
When a task that is to use an image library is built, Link sets 
linkages from the task to the appropriate library segments. =A 
maximum of 15 library segments can be used by a task running on 
a MAC machine; 191 libraries can be used by a task on ai MAT 
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machine. Once these linkages are sat, a u-task can read from or 
execute the image library segments.e |. Relocation/protection 
hardware prevents the task from writing to these segments. 


Image library segments are allocated to and deleted from memory 
by the operator with these commands: 


e LOAD.LIB 
® LOAD.SEG 


® KEMOVE.SEG 


Image library segments also can be loaded automatically at task 
load time. 


2-6 COMMON SEGMENTS 


Memory areas can be allocated for storing data that all system 
tasks can read from or write to. These areas are callei common. 


Local common segments located in local memory can be allocated, 
defined, and deleted by the operator with thesa commands: 


e TCOM 
e LOAD.TCM 
® LOAD.SEG 


@ REMOVE.SEG 


Data areaS can also be allocated for storing information that can 
be read or written to by all tasks under the control of two or 
more Perkin-Elmer procaessorse These areas, called global common, 
located in global memory, are defined and allocated by the system 
generation (sysgen) TCOM command. 


To the u-task, all common segments appear as a task commone A 
task common is a data area within the task impure segment that 
can be written to or read from only by the other segments within 
the task where it resides. An example of a task common area is 
that area of the impure segment used by the FORTRAN COMMON 
statement to store variables. 


Link initializes common segments. Because common areas can cross 
segment boundaries, tha size of a single common area is limited 
only by the amount of memory available. Link can dasignate a 
common as write-protected, allowing only one task to modify the 
segment; the remaining tasks can only read that area. 
Relocation/protection hardware prevents tasks from executing code 
in common areas. 
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The user defines the name of a global or local common. This name 
must correspond to predefined names given to these areas by the 
operator or at sysgen time. If a user-defined name of a common 
corresponds to a predefined nane, the user-defined common is 
automatically loaded in the resygective local or global common. 
If the name of a user-defined common does not correspond to a 
predefined name, the user-defined common becomes part of the task 
impure segment and is treated as a task common. 


Link is given the names of the predefined common areas. When a 
reference to a predefined common is encountered in the osbjacst 
code of the u-task, Link sets the appropriate linkage from the 
u-~task to the common. 


2-7 =TASK STATES 

Tasks can be resident or nonresident. A nonresident task is 
removed from memory after execution; a resident task remains in 
memory after execution. A task can be classified as resident by 


Link or at run time. 


A task in memory can b2 in any of these states: 


e Current 


® Ready 

e Wait 

eo Rolled — 

A task is in the current state while it is executing 
instructions. Only one task can be in the current state at any 


given time. All other tasks in memory are in one of the other 
states. 


A task is in the ready state when it is eligible to be 
dispatched; LeGay there are no obstacles to prevent it from 
becoming current. 


A task is in the wait state when it cannot become ready until 


some specific event occurs. Table 2-1 lists the wait states and 
their meanings. ; | 
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TABLE 2-1 TASK WAIT STATES 


WAIT STATE | MEANING 


Mee en ee ee ete EF Se a) OD wre emeee athe cimath Geen ee Gam mnem anee See eS eee eee men Oe ee ee es me ee enya cee ees eee ee SS Se tee ee cites ee te ems ee RP OE ee ne ew eee eee owen meee 
Ae ea Se A SR SS OOD SUED eaeee Sven GOD SUE GEE Gee TEN CUE: Sie OPE HED ems GME Os Smee Gene GOED TN RED GERD GUD GUE Seed CANE GER) um GET) Seem GE en ates GOED A mee SOS oe mt ee eee SE Se ae ae a me ee ee ee 


T/O wait Wait for an I/O operation to complete 


Connection wait Wait for a system resource 


Wait for an interval to elapse or for 
a particular time of day to occur 


Time wait 


Trap wait Wait for a task-handled trap to occur 


Load wait Wait for a requested load operation 
to complete 


Task wait Wait to be continued by another task 


Roll wait Wait to be rolled out 

Wait for I/0 to complete to 43 
terminal device (applies to terminal 
tasks only) 


Terminal wait 


Wait for an I/O queue to be freei 
when task reaches its QIO limit 


I/O queue wait 


Counters overflowed; task waiting for 
accounting facility to collect 
accounting data and remove wait 


Accounting wait 


Intercept wait Wait for an SVC to be executed 

Wait for system operator, user, or 
another task to instruct an inter- 
rupted task to continus execution 


Console wait 


Wait for system operator, uSer, or 
another task to initiate a task. 
After a task is loaded, it enters 
dormant state and remains there un- 
til execution is initiated. When a 
resident task goes to end of task, 
it reenters the dormant state 


Dormant wait 


A task is in the rolled state when its task impure sagment has 
been written to a direct access device. A task becomes rollable 
when it is specified as a rollable, nonresident task by Link. A 
rollable task is rolled out when a higher priority task requires 
its memory segment. It is rolled in when it becomes the highest 
priority rolled task and sufficient memory is available to 
accommodate it. : 
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2-8 SUBTASKING 


A subtasking facility allows one task (monitor task) to start, 
cancel, delete, and monitor the progress of th2 task it controls. 
The monitor task can set starting options and make logical unit 
(lu) assignments on behalf of the subtasks. The monitor task, 
using standard SVC 6 calls, can also control the task environment 
of its subtasks. 


The operating system informs the monitor task that the subtask: 


e® is‘paused, 

e has gone to end of task, 
e is suspended, 

e is released, 

® is rolled out/roliled in, 
e has been started, or 


e® has inherited subtasks from one of its subtasks. 
| 


To assign a task as a monitor, use SVC 6 to specify the subtask 
report option. The number of subtasks that report t3s a single 
monitor is unlimited. When all subtasks of a monitor go to end 
of task, the monitor is no longer referred to as a monitor. The 
normal SVC 6 functions that provide intertask communication and 
control are equally applied between monitor/subtask and 
subtask/monitor. 


By adding an entry to the monitor task queue and giving the 
monitor a task trap, the operating system informs a monitor of a 
subtask state change. Bit 15 of the current task status word 
(TSW) enables task queue entries for subtask state changes. fhe 
monitor services the subtask report when trap service is enabled. 


2.8.1 Tasks Loaded from Multi-Terminal Monitor (MIM) Terminals 


All tasks loaded and started from a user terminal execute as 
subtasks of MTM. Tasks executing under MTM will run at a maximuan 
priority of at least one less than the priority of MIM. 


Both interactive and batch processing are supported by MTN. Up 
to 64 interactive tasks can be executed concurrently, ons from 
each terminal. A terminal initiating an interactive task can be 
used to submit multiple batch jobs. Batch jobs are queued by 
MTM. The number of batch jobs that can executa concurrently is 
specified by the operator during MIM system start up. 
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CHAPTER 3 
TRAPS 


3.1 INTRODUCTION 


When certain events occur during the execution of a user task 
(u-task), the task can take traps to handle theme A trap 
suspends task execution and executes a special routine to handle 
the event. This routine can be a trap service routine or a task 
event service routine. When the event has been serviced, the 
u-task resumes normal execution. 


The user dedicated location (UDL) contains the dedicated 
locations required to use the trap service routinee For each 
type of trap that is supported, the UDL. contains locations for 
holding the old and new task status words (TSW) affected by the 
trap. When a trap occurs, the current TSW is saved in the old 
TSW location and the TSW in the new TSW location is loaded to 
become the current TSW. This TSW must point to the trap service 
routine written to service the type of trap caused by the event. 
After the trap service routine terminates, the contents of the 
old TSW location of the UDL are loaded into the new TSW Location, 
and the u-task resumes normal execution. No registers are saved 
asa part of the TSW swap that causes a trap service routine to 
be initiated. It is the responsibility of the trap service 
routine to save any registers it requires. FEFvents that can be 
serviced by the trap service routine ares: 


e@ Power restoration 

e® Arithmetic faults 

® Supervisor call 14 (SVC 14) execution 

e Memory access faults 

e [llegal instruction execution 

e Data format/alignment faults 

e The addition of items to a task queue 

Other events are handled through the task event trap service 
routine. This routine differs from the trap service routine 
described above in that the address of the routine is stored in 


the parameter block of the SVC that caused the trap rather than 
in the task UDL. ; 
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3.2 USER DEDICATED LOCATION (UDL) 


The UDL is an area occupying locations 0 through 255 (X°FF"') in 
each task impure memory space, preceding task code. It contains 
TSW swap areas and other data areas for communication batween the 
Operating system and the task. The queue entry and new TSW 
fields in the UDL are used only if the corresponding bits in the 
TSW are enabled. In Figure 3-1, the names in parentheses are the 
Symbolic names of the fields as defined:-in the UDL dAaisa 
structure. A SUDL macro call generates the struztures and 
equates for the UDL data structure. Figure 3-1 depicts the UDL 
structure. All fields are described following the figure. 
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ACSVC 14 arg) 
{ (UDL.«SV14) 


10(0) { 
| CTOP f 
| | (UDL.CTOP) | 
neo oe ae on me eet Oe oe ee On Oe oe we om tr ee ee ae oe oe we we we oe oe ae aaa i os aes ae acim baal aate | 
p4(4) l 
| UTOP | 
| (UDL.UTOP) | 
me ee em ee ee em we em me mene ewe oi Set 
188) | 
l 7 UBOT [ 
{ . (UDL.UBOT ) | 
| ee eae we ae ee we we ee ee ae eee we we eee we a ee ee ee ew ee ee cr aa | 
f12(C) { 
| Data management system | 
| (UDL.DMS) | 
SS aaa ae ere a ee et ee ee ee ey ee | 
{16(10) | 
| A(task queue) | 
| (UDL.«TSKQ) | 
ee ee nee ee ne me ae eee ee ee eae ee ee oe oe ee oe Oe ee oes oe 0S ee ee on ne Ow we Do ee es ee tr a | 
}20(14) { 
| Reserved | 
| | | 
a a a ae oe bod aa aac | 
}24(18) | 
A(message ring) | 
| (UDL.MSGR) { 
0 Oe Oe ee Oe OD Ow re Oe ee ee Om Oe Oe Oe ee Om Om me Oe OD OD OD am 8 OF De OD OD OF © 0 08 OS OH OF OD OP OP OD 08 OF OF OH OF OF OF om om 9 OD oe on oe oe | 
}28(1C) | 

| 


Figure 3-1 User Dedicated Location (UDL) 
Structure 
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| 32(¢20) | 
| (UDL.EXT1) i 
{ | 
ioe a odeaiaaes : Reserved —-—_—_ | 
{36(24) | 
| .(UDL. EXT2) 1 
| | 
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{40(¢28) | 
| | 
| | | 
abe achcaa alia Reserved 2S SS] 
144(2C) 
| | 
| { 
eee a ee eae eS ea as See ae aa SS ae Se | 
148(390) | 
| { 
{ | 
(ae =s Power restoration old TSW ~===-=-= | 
}52(34) CUDL.PWRO) | 
| | 
1 l 
[eee SHS SS eee ae ae Se SSeS Sea ene ee ee | 
{56(38) | 
| | 
| | 
(o+=+2- Power restoration new TSW = see--+- | 
}60(03C) (UDL.PWRN) . | 
| l 
| | 
PP ee cag ye, en eee gee aaa aa a a i 
164(40) . . | 
| | 
| | | 
Sees Arithmetic fault old TSH we emmn | 
,6ecuu) (UDL.ARFO) | 
| > 
| | 
Lesa r arse seer en eres Sere ee eee ae oS ee SSS Tee | 
}72(48) | 
| | 
| | | | 
[SSS —= Arithmetic fault new TSW Heme | 
}76(4C) (UDL.~ARFN) | 
| | 
| | 
DSR ate pa centre ea ees ae rae rete Sag ee pre ep ee ee | 
180(50) }8171¢51) {82¢(52) 183(53) | 
| Reserved | Reason code { Reason code | Reason code jf 
| { (CUDL.DFFR) | (UDL.MAFR) | CUDL.ARFR) | 


Figure 3-1 User Dedicated Location (UDL) 
Structure (Continued) 
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Address following arithmetic fault instruction 


| (UDL.ARFX) 

| [9m ear te ee one cams em et oe ene en we MY OD OF tee ane eee eee SS om SS One cat tam OD AOR ON SEN ED OS GED Uae GED OED OE ED GES GP OEY OD OU Oh OD ONE UEP yD Oem Ot am OS Om me om ab te om oD on 
{88(58) 

| Data format/alignment fault address 

| (UDL.DFFX) 

| oo em ee am oe oe em om we we om oe ee oe om oe os oe oh ee ww me Ow em em oe ee oe ee ee oe we oe ow oe oe oe dee ee om oe ee we ow oe oe oe me ee on 
}92¢5C) 

|. MAC/MAT fault, actual fault address 

1 (CUDL.MAFL) 

| = on on ae an an on em ew me ee Oe ee ee em re eee eee a Om we ee me em om oe me om Oe me oe ow om oe om Oe ae we we oe ne me oe a we oe ee et 
196(60) 

| 

! : 

= ees SVC 14 old TSW a eee 
}100(64) (UDL.~S140) | 

{ 

| Oe ae oe ON em ee an ae am om or om OF am oe ow aD am om ar ow on an ae as oo om om om <- an ae ar et oe ee wh ae oe oe oe ow oe het ee eb ee te am On ae aw ae oe ae an on 
}104(68) 

| 

I 
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| 
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Figure 3-1 


Structure (Continued) 


User Dedicated Location (UDL) 


48-039 FOO 


ROO 


ow OW wah ve ane Ge Om Gr a Om ee OD oe Ee ee Om ee OF aw om SP OF =D =F oD ot GP om OF @ OF HS ow aE TE On eh om om OF oD om oF ae am am C8 oF a om ow a a ow ow ow oF 


Memory access fault new TSW 
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Figure 3-1 User Dedicated Location (UDL) 
Structure (Continued) 
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(UDL. RSAV) 
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Figure 3-1 User Dedicated Location (UDL) 


Fields: 


CTOP . 
(UDL.CTOP) 


UTOP 
(UDL.UTOP) 


UBOT 
(UDL.UBOT) 


Data 
hanagement 
system 
C(UDL.DMS) 


ACtask aueue) 
(UDL.~TSKQ) 


Structure (Continued) 


is the top of the impure segment. After a 
fetch pointer (FETPTR) macro call, CIOP 
contains the program address of the highest 
halfword in the task impure segment. The 
value of CTOP which is defined by Link can be 
overridden at load time. 


is the user top. After a fetch pointer 
(CFETPTR) macro call is issued, UTOP contains 
the program address of the first fullword 
following the defined portion of the impure 
segment. The GETSTORE and RELSTORE macro 
calls manipulate the valusa of UTOP, which 
Cannot exceed the value of CTIOP by more than 
two bytes. . 


is the user bottom. After 4a fetch pointer 
(FETPTR) macro call, UBOT contains the 
program adiress of the bottom of the user 
program. For user tasks, this value is 0. 


is the field used by the data management. 
system and must contain zeros. 


is the field into which the user stores the 
address of the task queve. If the content. of 
of this field is zero, no task queua entries 
can be made, even if the ISW task queue entry 
bit is set. 
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Reserved 


A(message 
ring) 
(UDL.~MSGR) 


A(SVC 14 arg): 
(UDL.SV14) 


Reserved 
(UDL.EXT1) 
(UDL.EXT2) 


Reserved 


Power restora- 
tion old TSW 
(UDL.PWRO) 


Power restora- 
tion new TSW 
(UDL.PUWRN ) 


Arithmetic 
fault old TSW 
(UDL.ARFO) 


Arithmetic 
fault new ISW 
(UDL.-ARFN) 


Reserved 


Data format/ 
alignment 
fault reason 
code 
(UDL.DFFR) 
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is a field reserved for future use that must 
contain zeros. 


is the field into which the user stores the 
address of a 76~-byte storage arsa before 
receiving any messages. This storage area 
must be aligned on a fullword boundary. If 
the content of this field is zero, no message 
can be received, even if the TSW task queue 
entry on the message bit is set. 


is the field where the operating system 
stores the effective address of thea SVC 14 
argument when an SVC 14 trap occurs. 


is the field reserved for system use that 
must contain zeros. 


is a field reserved for future use that must 
contain zeros. } 


is the field where the operating system 
stores the task‘*s current ISW when a power 
restoration trap occurs. 


is the field into which the user stores the 


TSY to be loaded as the current [SW when a 
power restoration trap occurse The location 
counter portion of this TSW should contain 
the address of a power restoration trap 
service routine. 


is the field into which the operating system 


stores . the task’s current. TSW when an 
arithmetic fault trap occurs. For the 
Perkin-Elmer 3200 Series Processors, thea 


‘location counter portion of this ISW contains 


the address of the faulting instruction. For 
7/32 and 8/32 processors, the location 
counter portion of this ISW contains the 


address of the next instruction. 


is the field into which the user stores the 


ISW to be loaded as the current ISW when an 
arithmetic fault trap occurs. The location 
counter portion of this [SW contains the 
address of an arithmetic fault trap service 
routine. 


is a field reserved for future use that must 
contain zeros. 


is the field into which the operating system 
stores a reason code indicating the type of 
data format/alignment Fault when a data 
format/aligament fault trap occurs. 


Memory access 
fault reason 
code 

(UDL. MAFR) 


Arithmetic 
fault reason 
code 
CUFL.ARFR) 


Address 
following 
arithmetic 
fault 
instruction 
(UDL.~ARFX) 


Data format/ 
alignment 
fault address 
(UDL.DFFX) 


MAC/MAT 
fault, 
fault 
address 
(CUDL.MAFL) 


actual 


SVC 14 
old TSW 
(UDL.5140) 


SVC 14 
new TSW 
CUDL.~S14N) 


Task queue 
service 
old TSW 
(CUDL.TSKO) 


is the field into which the operating system 
stores a reason code indicating the type of 
memory access fault when a2 memory access 


fault trap occurs. This field applies only 


‘to the Perkin-Fimer 3200 Series ProceSSOrSe 


is the field into which the operating system 
stores a reason code indicating the type of 
arithmetic fault when an arithmetic fault 
trap occurs. This field applies only to the 
Perkin-Elmer 3200 Series Processors. 


is the field into which the operating system 


stores the address of the instruction 
following the instruction that resulted in 
an arithmetic fault trap. This field applies 


only to the Perkin-ELmer 3200 Series. Pro- 
CeSSOLr. 

is the field into which the operating system 
stores the address of the location in memory 
referenced by the instruction whith caused 
the alignment fault or the data format fault 
trape This field applies only to the 


Perkin-Elmer 3200 Series Ptocessors. 


is the field into which the operating system 


stores the address of the location that 
caused a memory access fault trap. The 
address. can be the effective address of data 
or the instruction address depending on the 
fault type indicated in the. memory access 
fault reason code field (UDL.MAFR). This 
field applies only to the Perkin-Elmer 3200 


Series Processorse 


is the field into which the operating systen 


stores the current TSW when an SVC 14 trap 
occurs. If SVC 14 traps are disabled in the 
TSW, the execution of an SVC 14 is illegal. 


is the field into which the user stores thea 
TSW to be loaded as the current ISW when an 
SVC 14 trap occurs. The location counter 
portion of this TSW contains the adiress of 


an SVC 14 trap servic2 routine. 


is the field into which the operating system 
stores the current TSW when a task queue 
service trap occurs. 
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Task queue 
service 
new TSW 
(CUDL.~TSKN) 


Memory access 
fault old TSW 
CUDL.MAFO) 


Memory access 
fault new TSW 
(UDL.MAFN) 


Illegal 
instruction 
old TSW 
(UDL.~IITO) 


Illegal 
instruction 
new ISW 
CUDL.~IITN) 


Data format/ 
alignment 
fault old TSW 
(UDL. DFFO) 


Data format/ 
-alignment 
fault new ISW 
(UDL.DFFN) 


Reserved 


Pointer to 


system network 


architecture 
table 
(UDL.SNA) 
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field into which 


is the the user stores the 
TSW to be Loaded as the current [SW when a 
task queue service trap occurs. The location 
counter portion of this TSW contains the 
adiress of the task queue trap service 
routine. 

is the field into which the operating system 


stores the current TSW when a memory iccess 


fault trap occurse. 


is the field into which the user stores the 
TSH to be loaded as the csurrent TSW when a 
memory access fault trap OCCULS. The 
location counter portion of this ISW contains 
the address of a ‘memory access fault trap 
service routine. 


is the field into which the operating system 
stores the TSW to be loaded as tha current 
TSW when an illegal instruction trap occurs. 


the user stores the 
TSW to be loaded as the turrent ISW when an 
illegal instruction trap occurse The 
location counter portion of this TSW contains 
the address of an illegal instruction trap 
service routine. 


is the field into which 


is the field into which the operating systen 


stores the task's current [SW when a data 
format or alignment fault trap occurs. This 
field applies only to oe Perkin-Elmer 3200 


Series Processors. 


is the field into which the user stores the 
TSW to be loaded as the current [TSW when 
a data format or alignment fault trap occurs. 
The location counter portion of this ISW 
contains the address of the data format fault 
or alignment fault trap service routine. 
This field applies only to the Perkin-Elmer 
3200 Series Processors. 

is a field reserved for future use that must 
contain zeros. 


the operating system 
the systen network 


into which 
address of 
table. 


is the field 
stores the 
architecture 


Save area isa field reserved for internal usa by data 
used by system communications network software. 

network 

architecture 

(UDL.RSAV) 


Reserved for is afield used by OS/32 AIDS that must 
ALDS contain zeros. 


User-supplied fields in the UDL; e.g, all new ISW fields andi the 
task queue and message ring address fields, can be assembled as 
constants or loaded during the task initialization phase. . Link 
builds tasks from program object code. Tasks containing a 
user-assembled JDL are specified by the Link command: 


OPTION ABSOLUTE=0 


This command Specifies that a UDL exists in the program and that 
storage should not be reserved for § it. If a task does not 
contain a user-assembled UDL and the ABSOLUTE parameter is 
omitted in the OPTION command, Link reserves 256 bytes of storage 
for the UDL at the beginning of the image load module. 


3.3 TASK STATUS WORD (TS¥) 


The TSW describes the task state at any time with respect to 
user-controlled interaction with the operating system. [SW also 
acts as a location counter for the task and enables ani disables 
the various task traps and additions to the task queue. A SISW 
macro call generates the TSW structures and equates. Figure 3-2 
depicts the TSW. ALL TSW fields are described following the 
figure. . 


he Ge ee ae ee ne ee ae he ee we a om ye Oe oe OE re On Oe ee ek a a ee Oy ee EE Oe ee FS SO HE ON EE ee We Oe a om oes an 


PwrePyPaAPS | QE"_EMET ERY Reserved x |} oDEUT 4 (E{LyjYo|ly2zyrF fy Rsvd f VY { cc 
Bits: : 
0 1 2 3 4 5 6 7 8 41 1 1 1 1 2 2 2 2 2 2 2 2 2 3 
a 5 6 7 8 9 0 1 2 3 0«4 5 6 7 8 1 
{ Reserved { Location counter 
Bits 
3 


Figure 3-2 Task Status Word (TSW) 
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Fields: 
OCTSH.WTM) 


1(TSW.PHRM) 


2(TSW.AFM) 


3(TSH.S14M) 


WC TSHW.TSKM) 


5(TSW.MAFM) 
6( TSW. LIT) 


7(TSW.DEFM) 


8~14(C Reserved) 
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is the trapv wait bit. Tf anabled, the task 
is suspended until a trap occurs. 


is the power restoration trap bit. Lf 
enabled, the task receives a trap when power 
is restored following a power failure. If 


disabled, the task is paused. 


is the arithmetic fault trap ° bit. If 


enabled, the task receives a trap when an 
arithmetic fault occurs. If disabled, the 


task is paused and a message is displayed on 
the user console. 


is the SVC 14 trap bit. I£ enabled, the task 
can use SVC 14 and receive a trap when an SVC 
14 is executed. If disabled, execution of an 
SVC 14 is illegal. Because SVC 14 is used by 
AIDS to set breakpoints, it must not be used 
in a task being debugged with OS/32 AIDS. 


is the task queue servite trap bit. I€£ 
enabled, the task receives a trap when an 


item is added to the task yueue or when a ISW 


With this bit set is loaded and the task 
queue contains items. If disablei, no trap 
occurs when item is added to task queue. 


is the memory access fault trap bit. If 
enabled, the task receives a trap when it 
attempts to access memory outside its task 
space. If disabled, the task is paused and 
a message is displayed on the user console. 


is the illegal instruction trap bit. If 
enabled, the task receives a trap when it 
executes an Lilegal instruction. If 
disabled, the task is paused and a message is 
displayed on the user console. 


is the data format fault and alignmant fault 
trap bit. If enabled, the task receives a 
trap when it executes an instruction that 
causes a data format or alignment fault. I[f 
disabled, the task is paused and a message is 
displayed on the user console, 


is a field reserved for future use that aust 
contain zeros. 


15°TSW.SUQM) 


16(TSW. DION) 


17(TSW.TCH) 


18( Reserved) 


19(TSW.PMM) 


20(TSW.LODM) 


21¢TSW.IOM) 


22(TSW.TMCM) 


is the subtask queue entry bit. If enabled, 
the task receives items on its quaue 
specifying a subtask state change. Let 
disabled, no items are entered on the task 
queue when a subtask state change otcurs and 
the notification of change is lost. 


is the task queue entry on device interrupt 


bite If enabled, an item is entered on the 
task queue when a trap iS received from an 
I/0 device. If disabled, no items are 


entered on the task queue when a device trap 
OccUrS. 


is the task queue entry on SVC 6 quaue 
parameter call bite If enabled, an item is 
entered on the task queue when a task issues 
an SVC 6 queue parameter option. If 


disabled, the cali to the task is rejected. 


is a field reserved for future use that must 
contain zeros. 


is the task queue entry on task message bit. 
If enabled, the task can receive a message 
from another task or the operator. The task 
queue receives the address of the message 
buffer. If disabled, no message is sent. 


is the task queue entry on completion of a 
load and proceed operation bit. If enabled, 
the task queve receives an item specifying 
the parameter block address of the 3VC 6 load 
call when the load is completed. LE 
disabled, no item is entered on the task 
queue when a load and proceed operation is 
completed. 


is the task queue entry on I/0 completion 
bits If enabled, the task queue receives an 
item specifying the address of the SVI 1 
parameter block when an I/O proceed call is 
completed. If disabled, no item is entered 
on the task queue when an I/O operation is 
completed. 


is the task queue entry on timeout rtompletion 
bit. If enabled, the task queue receives an 
item indicating a specified time interval nas 
elapsed. If disabled, the task iS not 
notified that a time interval has elapsed. 
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23(TSW.ITM) is the task queue entry on an SVC 15 buffer 
transfer, command execution, termination, or 
halt I/O bit. This function is supportei 
only by the data communicaions subsystem. If 
disabled, no item is entered on the task 
queue when one of the specified 
communications operations is completed. 


24-25 is a field reserved for system use that aust 
(Reserved) contain zerose 


26(TSW.TESM) is the task event trap bit. If enabled, the 
| — task can receive task events. If disabled, 
all task events are queued until a new [SW is 

loaded with the task event trap enabled. 


27(Reserved) is a field reserved for future use that must 
contain zeros. 


28~31(CC) ' is the current condition code contained in 
the program status word (P5q). 


32-39 is a field reserved for future use that must 
(Reserved) contain zeros. 
4O-63(LOC) is the location counter contained in the PSW. 


The task always has a current TSW. The initial TSW or the 
current TSW when the task is loaded is set by Link. If Link is 
not requested to set an initial TSW, the ititial TSW defaults to 
all zeros (no traps or queue entries enabled). Phe initial 
location counter defaults to the starting address, if a. transfer 
address is specified at assembly time, or to the start of the 
impure segment, if a transfer address is unspecified. 


A task can change its current TSW at any time by issuing an LISW 
macro call. The TSW must be loaded in an 8-byte area aligned on 
a fullword boundary. The first fullword of the ISW contains the 
status, and the second fullword contains the Location counter. 
Following an LTSW macro call, the taSk resumes execution at the 
location specified in the loaded TSW. If only the status of the 
current TSW is to be changed, a value of zero should be specified 
in the location counter portion of the new TSW. In this case, 
execution resumes with the instruction following the macro call. 


3-4 TASK TRAP SERVICE ROUTINE 
There are seven types of task traps that can be handled by a task 


trap service routine: 


r) Power restoration 


e Arithmetic fault 
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e SVC 14 

oe Memory access fault 

. Titegas instruction 

e Data format/alignment fault 


e® Task. queue service 


3.4.1 Power Restoration Trap 


A power restoration trap occurs after power is restored following 
a power failure and the TSW.PWRM bit in the TSW is set. The 
current TSW is stored in the UDL.~PHRO field, and the new [SW in 
the UDL.~PWRN field is loaded and becomes the current [SW. The 
location counter of the new TSW should contain the addr2ss of the 
power restoration trap service routine. This trap service 
routine exits by issuing an LTSW macro call to load the [5H 
stored in the UDL.~PWRO field as the current TSW. 


3.4.2 Arithmetic Fault Trap 


An arithmetic fault trap occurs when one of the events Listed in 
Table 3-1 Occurs. 


TABLE 3-1 ARITHMETIC FAULT TRAP-CAUSING 


EVENTS 
| | REASON | 
| EVENT } CODE | 
J Hae aSHt eS Set as ese SS SS SSeS SSSe SSeS SS SS Sse SSS=s= | 
Fixed point zero divide X¥*00° 
Fixed point quotient overflow KO" 


Floating point exponent underflow 
Floating point exponent overflow 


| 

: | | 

Floating point zero divide } x*O2° 
| 
| 


When an arithmetic fault occurs with the TSW.AFM bit set in the 
TSW, the current TSW is stored in the UDL.ARFO field, and the new 
TSW in the UDL.ARFN field is loaded and becomes the current I[5HW. 
The reason code is stored in the UDL.ARFF field. The location 
counter of the new TSW contains the address of the arithmetic 
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fault trap service routine. The action taken when an arithmetic 
fault trap occurs depends on the options specified by Link and 
the traps enabled in both the TSW and the PSW. Table 3-2 #£4shows 
actions taken when combinations of different options are 
specified. The trad service routine exits by issuing an LISW 
macro call to load the TSW stored in the UDL.ARFO fi2li as the 
current TSW. 


TABLE 3-2 ARITHMETIC FAULT TRAP ACTION | 


| LINK | | 
| ARITHMETIC | ARITHMETIC] 
| FAULT BIT | FAULT I | 
| SETTING IN TSW| OPTION { ACTION TAKEN | 
J HSS essa asnessn sess esr ess ass Sse sses asses sssssa=s| 
} 1 | AFCONT | Trap occurs i 
{ 1 | AFPAUSE | Message/paused { 
{ 0 { AFCONT | Message/continued | 
| Oo | AFPAUSE | Message/paused | 
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3.4.3 SVC 14 Trap 


SVC 14 is a user-defined SVC, and its function is performed in 
the SVC 14 trap service routine. An SVC 14 trap occurs when an 
SVC 14 is executed with the TSW.S14M bit set. The current ISW is 
stored in the UDL.S1T4O field, the new TSW stored in the UDL.S14N 
‘field is loaded and becomes the current TSW, and the address of 
the SVC 14 argument is stored in the UDL.SV14 field. The address 
of the SVC 14 argument can be used by the trap service routine. 
This trap service routine exits by issuing an LISW macro call to 
load the TSW stored in the UDL.S1490 field as the current ISW. 


ATDS also uses SVC 143: therefore, SVC 14 must not be used by a 
task that is to be debugged by AIDS. 
3.4.4 Memory Access Fault Trap 


A memory access fault trap occurs when one of the events’ Listed 
in Table 3-3 occurs. 
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TABLE 3-3 MEMORY ACCESS FAULT TRAP-CAUSING EVENTS 


= ee ee ek ee oe oD em om on a aw om an am Se SF we = ee OF 6m 6m ow am SS oe Be oe we oe oe Ow ot P08 oe oe Po oe oe oe et Om oF we oe ee ew oF a OF ee om 


| | | REASON | 
| PROCESSOR } EVENT | CODE | 
{| 3220 | SVC address error } x°90° | 
{ | Execute protect violation ee Se’ | 
| | Write/interrupt protect violation | X'92' | 
| | Reserved } X'O3* | 
| | Write protect violation } x*’ou" - | 
| | Reserved } x°o5" | 
| | Reserved ; i. ¥736" | 
| |] Reserved ae Gas ef Sa 
{ | Segment number not present {| X*os8° | 
| |} Reserved | } x'o9° | 
| | Program address is greater than | | 
| | segment Limit fault (SLF) } XDA | 
lperbapueeiaret ys cage ie wid ie cei Seaetnasr ee see | 
} 3240 | Reserved } x*o90° | 
| | Execute protect violation } X*'o1' | 
| | Write protect violation ) X*92" | 
| { Read protect violation DX 3" | 
| } Access level fault } x*oa°" | 
| {| Segment limit fault cx 95* || 
| | Nonpresent segment fault {| X°96" | 
| | Shared segment table (SST) size | | 
| ! exceeded { x°97° | 
| } Private segment table (PST) size | | 
j | exceeded {, x*98" | 
All protection Violations are detected — by the > 


relocation/protection hardware. 


When a memory access fault occurs with the TSW.MAFM bit set, the 
current TSW is stored in the UDL.MAFO field, the new [SW in the 
UDL.MAFN field is loaded and becomes the current TSW, the 
faulting instruction address is stored in the UDL.MAFL field, and 
a reason code is stored in the UDL-MAFR field. The new ISW 
location counter should contain the address of the memory access 
fault trap service routinee This trap service routina exits by 
issuing an LTSW macro cail to load the ISW stored in tha UDL.MAFO 
field as the current TSW. 


3.4.5 Lllegal Instruction Trap 
An illegal instruction trap occurs after a u-task executes an 
illegal instruction with the TSW.-IITM bit set. The current [SW 


is stored in the UDL.IITO field, and the new TSW in the UDL.IITN 
field is loaded and becomes the current TSW. The new IswW 
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location tounter should contain the address of the illegal 
instruction trap service routine. This trap service routine 
exits by issuing an LTSW macro call to load the ISW stored in thea 
UDL.IITO field as the current TSW. 


3.4.6 Data Format/Alignment Fault Trap 


A data format or alignment fault trap results when one of the 
events listed in Table 3-4 occurs. 


TABLE 3-4 DATA FORMAT/ALIGNMENT FAULT 
TRAP-CAUSING EVENTS 


—- on ot On on am am Gy oe om ED OP ae owe em Om OP Oe oe no ee a Oe aw Om ee a ee ee ee ae oe ce om GS ae BS am aD ame oe OD 


| | REASON | 
| EVENT } CODE | 
| s=S SSS SS SSCS SSS SST SSS ISS SSS SS SS ST SS SSS SS SSS SS = | 
{| Reserved } x°00o° { 
| Reserved {| x*'oi' | 
| Invalid sign digit, packed data | X‘'02" | 
{ Invalid data digit, packed data | ¥°03° | 
| Reserved | x*o4' | 
| Reserved { x'o5* | 
| Fullword alignment fault | xX*06° | 
| Halfword alignment fault } x'o7° | 


When a data format or alignment fault trap occurs with the 
TSW.DFFM bit set, the current TSW is stored in the UDL.DFFO 
field, the new TSW in the UDL.DFFN field is loaded and becomes 
the current TSW, the address of the location in memory referenced 
by the faulting instruction is stored in the UDL.~DFFX field, and 
the reason code is stored in the UDL.~DFFR field. The new ISW 
location counter contains the address of the data format or 
alignment fault trap service routine. This trap service routine 
exits by issuing an LTSW macro call to load the ISW stored in the 
UDL.DFFO field as the current [SW. 


3-4.7 Task Queue Service Traps 


A task queue service trap results when one of the events'7 Listed 
in Table 3-5 occurs. 
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TABLE 3-5. TASK QUEUE SERVICE 
TRAP-CAUSING EVENTS 


— a = = aw a ew ee ee we ae we Ge oe oe ee ee oe we eee ae oe oe ee ee em oe ee oe ee er we ee ow ae ow a ae 


| | REASON ] 

| EVENT | CODE | 

| Spee as StS Sara SS See SSeS TSS eee SSS STS SESH s=] 
Device interrupt X*OO° 
Queue parameter X'O1" 
Subtask state changes X*02° 
Reserved X¥*03° 
Reserved X¥’ou!s 
Reserved K*Q5° 
Message received X¥*'Q6° 
Load and proceed completion X*O7' 
I/O proceed completion X*98° 
Timer termination X°O9° 
SVC 15 command execution x OR 
SVC 15 buffer transfer. X°OB’ 
SVC 15 termination K*°Oc’ 
X*OD' 


| 
| | 
| | 
| 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| | 
| svc 15 halt I/0 | 
} ZDLC buffer input : | X°E° 
| | 
| | 
| 
| | 
| | 
| | 
| | 
| 
| | 
| | 
| 
| | 
| | 


ZDLC buffer output X°OF’ 
ZDLC error condition X¥*710° 
ZDLC buffer error x°11° 
Reserved X'12° 
Reserved LT 3" 
Reserved K' 74° 
Reserved K*°45* 
Reserved » Gaaae (hos 
Reserved ) Gates (ee da 
EMT3270 unsolicited input X¥'18° 
EMT3270 unrequested disconnect X*179° 
EMT3270 switched line connect 

timeout X'1A° 


Except for the subtask change event, all items added to the task 
queue are four bytes long and have the following format: 


ee eet OD ee ee Oe eee ane Ge ae ee Get ate ee ee ee we ee ee amy ee ee eee oe ee ee ee om ae om ow 


{ code {f{ Parameter | 


ee ee Oe EF ee ee ee ee ey omy emt ons EE ew am ee em ee ae a ame ey ee ee oe oe 
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Fields: © 


Reason code is a I-byte hexadecimal number specifying the 
reason why the trap occurreil. See Table 3-5. 


Parameter is a 3-byte parameter specifying additional 
information about the particular item adieji to 
the task queue. See Table 3-6. 


TABLE 3-6 PARAMETERS ENTERED ON THE TASK QUEUE 


nae eee ee cee EF GFR Gert Se ee eae es Ge GS UD ie cen Ge Rt dh eRe OD am Gee em Gee ee ce aes GED UD OD Oe ele Gee ee eh Gee GED Go aon ED GW we elm OD ee a ew OP a eee om Pe oe oe om oD 


Associated with device 
Specified by sending task 
Type of state change 
A(message ring) 

ACSVC 6 parameter block) 
ACSVC 1 parameter block) 
Specified in call 

SVC 15 command AC(SVC 15 parameter block) 
SVC 15 buffer ACSVC 15 varameter block) 


| Device interrupt | 
| | 
| { 
| | 
| | 
i | 
| | 
| { 
{ | 
} SVC 15 termination |} ACSVC 15 parameter block) 
| | 
| | 
{ | 
| | 
| | 
| | 
| | 
| | 
| | 


Queue 

Ssubtask state changes 
Message received 

Load and proceed completion 
I/O proceed completion 
Timer termination 


SVC 15 halt I/0 ACS¥C 15 parameter block) 
ZDLC read done ACUDR list) 

ZDLC write done ACUDW list) 

ZDLC general error ACinformation block) 

ZDLC buffer exhaustion error ACUQR list) 

EMT3270 unsolicited input 

EMT3270 unrequested disconnect 

EMT3270 switched line connect 


——= ae EP ow Ga eae Om ee ee ee Sees jem Ce Ge meee Ge One eee Se Gee aw 


timeout 
NOTE 

For more information, see the OS/32 Bit 

Synchronous Communications Reference 

Manual. 
Subtas* items in the task queue are three fullwords long. Using 
three add to the bottom of the list (ABL) instructions, the 
operating system adds items to the bottom of task queue. The 


three fullwords form a 12-byte entry as folloys: 


i {Subtask | | 1 
{ Reason | reason | — TCI | Taskid { 
{| code | code =| I 2 Q I 
Bytes 

0 4 2 3 4 11 
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Fields: 


Reason code is a 1-byte field indicating a subtask state 
change occurred. 


Subtask ‘is the i-byte field that defines the 

‘reason code particular subtask state change that 
occurred. See Table 3-7 for possible subtask 
reason codes. . 


TCI is a 2-byte field that provides additional 
information specific to asubtask state 
change. 

Taskid is an 8-byte field that indicates the name of 


the subtask. 


TABLE 3-7 SUBTASK REASON CODES (RC) AND 
CORRESPONDING STATE CHANGES t 


2 os ee a ew ow ee oe a ow em me ww oe ow = we ow oe oe oe ow OF Oe a ow oom oe ws oF ow oe Ce ee oe oe OF Om o> on on a ow 


| SUBTASK | | 
| RC } SUBTASK STATE CHANGE | 
[iG  @end.ee wash) Brees Ganda cea” | 
| | binary end of task codes | 
a eieee as 
io. ‘yeonttuneg 
‘3 “fsaea CO | 
(a  (eeeeee | 
fe iene ee | 
6 | Rolled in Oe | 


| 7 | Started by a task other than the | 
| } monitor 


— a ew ee ee ee ee ew a am ae a om aw a a oF ae we aP ws am Se a © ow aH am UH os CF BF OF Um am OP Am GF a oF FF w= a ow 


When a task queue service trap occurs; ieee, an item is contained 
in the task queve ani the bit is set, the current TSW is stored 
in the UDL.'ISKO field, and the new TSW is loaded in the UDL.ISKN 
to become the current [SwW. The new TSW location counter contains 
the address of the trap service routine. The trap service 
routine must issue a remove from top of list (RTL) instruction to 
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remove an item from the task queue. The item in the queue then 
can be examined to determine the reason the trap occurred, and 
appropriate action can be taken. This trap service routine exits 
by issuing an LISW macro call to load the TSW stored in the 
UDL.e-TSKO as the current TSW. If additional items are on the task 
queue when the old TSW becomes the current TSW, a trap occurs 
immediately. 


OS/3z2 also allows a task to receive a trap from external 
trap-generating devices. The 8-line interrupt module driver can 
add an item to a task queue in response to a. device interrupt. 
If task queue service is enabled, the addition to tha task queue 
can cause the task to take ae trap. Currently, the only 
Perkin-Elmer driver that supports trap-generating device 
functions is the 8-line interrupt module driver. Users can write 
their own trap-generating device drivers. 0S/32 provides the 
following functions for handling trap-~generating devices. 


e Connect - attach a trap-generating device to a task 
e Thaw - enable interrupt ona trap-generating levice 
e Sint - simulate an interrupt on 4a trap-~generating ievice 


(addition to Instrument Society of America (ISA) standards) 
@ Freeze - disable interrupts on a trap-generating device 


e Unconnect - detach a trap-generating device from a task 


These functions implement the entire ISA proposed standards for 
process control. 


3.5 TASK EVENT SERVICE ROUTINE 


Events that cause task event traps to occur are always associated 
with previously issued SVCs. The address of the routine that 
services the task event trap is stored in the parameter block of 
the SVC that generates the trap. . 


To take a task event trap, a task must have the TSW.TESM bit in 
the TSW enabled. If the TSW bit is not set, the task event trap 
will be queued until a TSW is loaded with this bit set. In 
addition, a task cannot take a task event trap while executing a 
service routine for a previous task event trap. Task queue traps 
and task event traps that occur during execution of a task evant 
trap service routine are queued until the task issues the TEXIT 
macro to axit from the routine. 
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During execution, the task event service routine can resteiva data 
that is in register 0, 1, or’ 2 that pertains to the trap. The 
data contained in these registers before the trap was taken will 
be lost unless the TEQSAVE option is specified during LINK. 
Specifying the PARTIAL parameter for TEQSAVE allows TIEQSAVE to 
save the contents of registers 0, 1, and/or 2 that pertain to the 
trap and to restore those registers after the task exits from the 
routinee Specifying the ALL parameter allows all registers to be 
saved and restored; no registers are saved if the NONE parameter 
is chosen. 
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CHAPTER 4 
SYSTEM MACROS AND STRUCTURES 


4.1 INTRODUCTION 


The Common Assembly Language/32 (CAL/32) Assembler symbolically 
references numerical constants and constant displacements within 
a data structure. 


Code written using symbolic references is easiar to upiate than 
numeric code. In addition, symbolic references are easier to usa 
because it is easy to remember a name. Errors involving 
references are less likely because an inaccurate numerical 
constant can still be assembled while an inaccurate symbolic name 
is recognized as an undefined symbol that cannot be assembled. 
Assembly language symbolic names can reflect the meaning of the 
numerical constant represented or the name of the field the 
Symbol points to within a structure. 


Numerical constant symbols and displacement symbols are used 
throughout O0S/32 coding. These same symbols and structures are 
used equally by assembly language programmers writing programs to 


run under 0OS/32. The collection of symbols and structures 
related to 05/32 is contained in the operating system structure 
macro library supplied with the system source (filename 


SYSSTRUC.MLB on disk). Individual structures can be included in 
the user task (u-task) by calling the appropriate macro. 


4.2 EXAMPLES USING SYSTEM MACROS 

The following example shows task status word (ISW) construction. 
The status portion of a TSW enabling trap wait, task queue 
service trap, queue entry on task call (queue paramater from 


another task), and I/0 proceed termination can be written as 
follows: 


Example: 


DC =—-s TSW.WEMITSW.TSKMITSW.TCMITSW.IOM 
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This sequence instructs the assembler to perform a logical OR 
operation on four masks, each mask setting a particular bit, to 
form a word with all the required bits set. Within the data 
structure, symbols defining bits are in two forms: 


® Symbols ending in M have the value of the bit mask needed to 
enable a particular bit. 


e Symbols ending in B have the value of the bit position. 


The following example illustrates loading a TSW into the user 
dedicated location (UDL). A TSW, enabling queue entries on I/9 
proceed termination and timeout completion, is loaded into the 
task queue service new TSW field of the UDL. This allows ctteue 
entries for these two events to continue while the task queue is 
being serviced. The TSW contains a location counter field 
pointing to the task queue service routine. 


Example: 


SUDL 


LM R14,TSKOTSH 
STM R14, ISDL.TSKN 


QSERVICE EQU i 


TSKOTSW DC TSW.ITIOM!TSW.TMCM,QSERVICE 


The UDL field can be referenced by its displarement within the 
UDL alone rather than in combination with a pointer to the 
beginning of the UDL. This is because, in an O5/32 user task, 
the UDL begins at address 0O within the task program address 
space. The one line definition of the TSW (ISKQTSW) generates 
two fullwords: a Status portion, enabling certain bits, anda 
location counter (LOC) portion, pointing to the task queue 
service routine as QSERVICE. 


The following example illustrates loading an SVC 6 function code 
into an SVC 6 parameter block. A function code specifying load 
and start immediately for some other task, aS opposed to a 
self-directed SVC 6, is loaded into an SVC 6 parameter block. 
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BXaAMDpLes 


SSVC6 
LI R1,SFUN.DOMISFUN.LMISFUN.SIM 
ST R1,PARBLK+SVC6.FUN 


PARBLK EQU * 
DS SVC6. 


The DS SVC6. instruction reserves the proper amount of spaces for 
the SVC 6 parameter block. SVC6 is the labal of the structure > 
defining the SVC 6 parameter block, and is set by CAL/32 to the 
size of the data structure defined by the $SVC6 macro. 


A field within a data Structure can be referenced using 4 
structure by directly referencing a field. 


Example; 


ST R1,PARBLK+SVC6.FUN 


The field also can be referenced using an index register. 


Example: 
eae 
i R3,PARBLK 
: Elon coe EUNCRS) 
PARBSLK - SVC6. 
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The direct method does not use an additional register, while the 
index register method passes the address of iifferent parameter 
‘blocks through a register (perhaps to a subroutine). 


The previous examples deal with applications where a program 
dynamically loads various fields with appropriate values. This 
approach is correct when the contents of the various fields 
change with time and must be dynamically initializei and 


subsequently changed. However, for applications where the 
contents of fields are static, there is an alternative that 
permanently assembles the appropriate values into data 
structures. This alternative saves both assembly code size and 


execution time. 


This example shews how to assemble values into a UDL. Assembling 
a UDL into a task requires an OPTION WORK=n command when linking. 


Example: 
SUDL 
TUDL EQU * 
ORG TUDL+UDL.TSKQ 
C task queue addr 

ORG TUDL+UDL.PWRN 
DC status,loc 
ORG TUDL+UDL.S14N 
DC status,loc 
ORG TUDL+UDL.TSKN 
DC Status,loc 


ORG TUDL+UDL 


The label TUDL is used to avoid conflict with UDL whith is 
defined in the UDL structure by the SUDL macro. To omit any of 
the field definitions from the code, delete tha ORG corresponiing 
to the relevant field and the constant definition for that field. 
ORG TUDL+UDL sets the location counter past the end of the UDL. 


This example shows how to assemble taskid and function coie into 
an SVC 6 parameter block. 
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Example: 


PARBLK EQU 


ORG PARBLK+SVC6. 
parameter block. 
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u 

* 

PARBLK+SVC6.ID 

C*TASKA* TARGET TASKID 
PARBLK+SVC6,.FUN 


SFUN.DOM!SFUN.SIM START IMMED. FUNCTION 


PARBLK+SVC6, 


sets the location counter past the end 


of 


the 


CHAPTER 5 
VOLUME, FILE, AND DEVICE INFORMATION 


521 INTRODUCTION 


To provide device independent I/0, programs direct ali I/9 
requests to a logical unit (lu) rather than to a specific device. 
or file. The system maintains an lu table (LTAB) for each task. 
The lu numbers, which range from 0 to 254, correspond to entries 
in the task LTAB. Task logical units must be assigned to 
specific devices or files by an operator, multi-terminal monitor 
(MIM) command, or a supervisor call 7 (SVC 7) (via macro) prior 
to their use. Devices can be marked offline, making then 
unavailable for assignment by user tasks (u-task). All OS/32 
supported direct access devices can be accessed through the file 
Manager which provides volume and file managemant Services. 


Data on a direct access device is organized into a series of 
files ona named logical volume. When a direct access device is 
made available by the operator command MARK ON, the name2 of the 
volume mounted on that device is associated with the ievice and 
refers to it. A MARK OFF command allows the mounted disk volume 
to be removed from the device list. A disk mounted without first 


being marked offline can be marked online only in asés 
Write-protected mode. If a disk is not marked offline before 
dismounting, further Writing to the disk might make any 


information in an indeterminate state unrecoverable. 

Before using a direct access volume, the appropriate iisk 
formatter program must format it, and the 0S/32 Disk Initializer 
Utility must initialize it. In addition, the Disk [nitializer 
Can send an operating system image to a direct access volume for 
BOOT loading. . 

5.2 V¥OLUME ORGANIZATION 


A direct access volume under OS/32 contains several data 
structures: 


e Volume descriptor 

e Sistiwe allocation (bit) map 
® file directory 

e Contiguous file type 


® Indexed file type 
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A u-task cannot access the first three structures. The operating 
system uses them to control the rest of the storage on the 
volume. 


The bulk of the storage area is used for file storage. All the 
files on the volume are indexed or contiguous file types. The 
amount of storage on the volume is the only limit on the number 
of files on the volume. A task, macro, or an operator or MIM 
command initiates file allocation, assignment, and deletion. 
Generally, file storage is permanent. A file remains on the 
volume until it is deleted. 


For applications requiring temporary storage, IS/32 also supports 
temporary files. The temporary file is like any other file 
except that when a temporary file is closed, it is automatically 
deleted. A temporary file can be a contiguous or indexed file 
type. . 


5.2e1 Volume Descriptor and Sector Allocation Map 
Sector 0, cylinder 0 of a disk volune contains the volume 


descriptor. The volume descriptor has six fullword fields. s5ee 
Figure 5-1. | 
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$0(0) | 
| Volume name | 
- | 
44) | 
| Attributes | 
: | 
}8(8) | 
| Pointer to file directory { 
| | 
}12¢C) | 
| [ 
| . | 
[SSS => Reserved 400 2 2 2 2 2 2 eiiseeceit | 
116(10) | 
i 
| ! 
{20(14) 
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Figure 5~1 Volume Descriptor Structure 
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Fields: 


Volume name “is the volume name field that contains a 
t-character ASCII volume identifier, the name 
by which the volume is known to the system. 


Attributes when the disk is marked off, the attributes 
field is 9: when the disk is marked on, bit 
0 of the attribute field is set to 1. 


Pointer to contains the address of the first sectors of 

file directory the primary file directory. The file 
directory contains information the systean 
needs to process files recorded on the 
volume. An entry in tha directory is nade 
for each file. 


Reserved is an 8-byte field reserved for future uSe. 
Pointer to contains the address of the first sectors of 
sector the sector allocation mape The allocation 
allocation map is a bit map containing one bit fFor each 
nap sector on the volume. Tais map records 
allocated, unallocated, and defective 
sectors. If a sector is allocated or 

defective, its corresponding bit in the 


allocation map is set to 1; if unallocated, 
it is set to 0. 


The Disk Initializer Utility initially places 


all data in the volume descriptor. 0S/32 
does not modify any portion of the volume 
descriptor, except to indicate the 


Online/offline state of the volume. 


5-2e2 Primary and Secondary File Directory 


The file directory consists of two sections: 


@e Primary directory 
® Secondary directory 
The primary directory is organized as a forward-linked list of 


I-sector blocks ona disk. A directory block contains spate for 
five file entries. Each entry contains information about the 


file: name, type, length, protection keys, data created, and 
data written. Since only one directory block tan be in- memory at 
one time, only five file entries can be memory resident. The 


other directory blocks remain on disk and ars accessed by I/0 
operations. 
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To reduce file search time, a secondary directory is available as 
a system generation (sysgen) option. The secondary directory, 
portions of which are in memory, is a contiguous file with the 
reserved name SYSTEM.DIR. This directory contains filenames and 
primary directory block pointers for all the files on the volume 
plus available slots (an expansion factor) for a user-defined 
number of files yet to be allocated (default 1390). The secondary 
directory is organized so that 20 file entries are contained 
Within each sector. The number of secondary directory sectors 
resident in memory is dependent upon the parameters set by the 
MARK ION command. 


If a secondary directory runs out of free file slots, the 
operator can choose to continue with a mixture of primary and 
secondary directories (at a cost in file search time), or mark 
the disk off and then mark the disk on with an additional 
expansion area. 


5.3 FILE TYPES 


OS/32 supports two file types: 


e Indexed 


e Contiguous 


In most cases, the same data manipulations can be performed on 
both file types. The choice of file type usually depends on how 
the data is to be accessed and not the data type to be put in the 
file. Each file type is optimized for one specific form of 
acceSSe 


File descriptors (fd) are entered in a Standard format. 


Format: 
voln: file class 
[ fitename | |. [ext] ] / 
dev: actno | 
Parameters: 
volns is a 1- to 4 -character alphanumeric string 


specifying the name of a disk volume. The 
first character must be alphabetic and the 


remaining, alphanumeric. If the volume nama 
is omitted, the default is the system or user 
volume. 
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dev: 


filename 


eext 


file class 


actno 


Some Perkin-Elmer 


is a 1- to 4-character alphanumeric string 
specifying a device name. The first character 
must be alphabetic ani the remaining, 


alphanumeric. 


is a 1- to 8-character alphanumeric string 
specifying the name of a file. The first 
character must be alphabetic and the 
remaining, alphanumeric. If a filename is 
Specified when a device name is specified, the 
filename is ignored. | 


is a 1~ to 3-character alphanumeric string 
specifying the extension to a filename. 


is a 1-character alphabetic string specifying 
the type of file class in a syst2m running 
under MTM. The file class types are: 


- PP for private file 


for group file 


GQ 


-~ S$ for system file 


is a I-character string specifying the system 


account number. Lf MIM is not being useli or 


if the operator is using the system console, 
the file class is the account number. If this 
field is omitted, the default value is 0 or 
the system account. Any other account must be 
specified by typing the slash (/) ani 4 
Gecinal number within the range of 0 through 
Pie or 


programs are shown in Table 54 with 


recommended filename extensions. 
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TABLE 5-1 PERKIN-ELMER I/O FILENAME 


EXTENSIONS 
| | INPUT | OUTPUT | 
| PROGRAM OR (js SSeS Soe See eee See ee | 
| COMMAND NAME  ] EXTENSIONS { 
| SUES SRS SSS Sess SS SSS SSH Sees SSeS SSS SSS SSSS=== |] 
{ BAS325, BAS32D { BAS } BAS 1 
| CAL32 { CAL | OBJ | 
| COBOL | CBL | CAL |. 
| CORAL | CRL | OBJ l 
} F7D | FIN {| CAL, OBJ | 
| F70 | FIN { OBJ | 
{| LIBLDR . {| OBJ | OBJ ! 
j} Link | OBJ,SEG } TSK,SEG | 
| SBUILD command | ; } cSS | 
| BUILD commani | { CSS { 
| CALMAC32 {| MAC,MLB } CAL | 
| Pascal | PAS | OBJ | 
| Patch | OBJ,TSK,SEG | OBJ,ISK,SEG | 
| PPG | RPG | OBJ | 
5-3-1 Indexed Files 
Indexed files are supported on all disk storage devices. The 


indexed file is an open-ended file composed of a chain of iniex 
blocks and a series of data blocks. The index blocks are linked 
together and contain fullword pointers to one or more data 
blocks, depending on the number of blocks in the file. The index 
and data blocks of the indexed file are transparent to the user. 


The user allocates data block size, index block size, and logisal 
record size. These parameters are fixed until the file is 
deleted. Data block size and index block size are specified in 
sectors (multiples of 256 bytes). ‘Logical records are physically 
blocked into data blocks. 


An indexed file can be sequentially or randomly accesseil. These 
two access methods can be mixed without closing and reassigning 
the file. Because of the Dhysical structure of the fila, raniom 
access is readily performed. For example, to read block 1 and 
then block 60, the indexed file structure requires an overhead 
read operation for the index block containing the pointers to 
blocks 1 and 60. 


The open-ended structure of the indexed file allows the file to 
be sequentially extended by writing a logical record numbered one 
greater than the number of existing records. If five records are 
currently ina file, a request to write recori § causes the file 
to be extended. However, if there are currently five recoris, a 
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. 


request to write record 7 or higher causes an end of file (ESF) 
status. The file can be updated by writing over an existing 
record. 


Indexed files can have shared write access privileges (SRW, SWO, 
ERSW) that allow more than one task to concurrently append or 
update an indexed file. Indexed file I/O raturns EOF. status 
if as 


e read sequential operation is attempted at. the end of file; 


® read random operation is attempted and the logical record 
number specified is greater than the total number of logical 
records in the file; or 


e® write random is attempted and tha Llogizal record number 
specified is greater than the total number of logical records 
in the file, plus one. 


End of medium (EOM) status is returned if a write Operation is 
attempted without enough space on the volume containing the file. 


If an I/O error occurs during a read operation, I/O is terminatad 
and the I[/0 error status is returned to the user. If an I/0 
error occurs during a write operation, data is not written. The 
system returns thea file to its last known state, adjusts the file 
information in the FCB, and returns an I/O error status to tha 
user. The user should checkpoint the file and issue a fetch 
attributes macro (FETAIR) to obtain the current status of the 
file. 


A forward file or backward file operation positions an indexed 
file at the end or beginning, respectively. 


ASCII, binary, and image operations all are Supported on indexed 
files. Also supported ar2 test and set, write filemark, forward 
space filemark, and backspace filemark operations. 


The block containing the current record pointer or I/0 masro that 
specifies the start of a logical record is read into a system 
buffer. The contents of the system buffer are then transferrei 
to the user-specified buffer until the user buffer is full or the 
number of bytes egual to the logical record length of the file 
has been moved. When the current record pointer is set to the. 
record following the accessed record, the transfer is complete. 


Output operates the same way as input, except that the data is 
moved from the user buffer to the system buffer. If a current 
record pointer value of one greater than the last recori in the 
file is specified, a record is appended to the file, thus 
allowing the file to he extended at any time. If the size of the 
specified buffer is less than the logical record length, the 
record is padded on the end with spaces (ASCII format) or zgaros 
(binary format). 


The test and set macro, TESTIO, provides record lscking to 
synchronize simultaneous updates. 


The advantages or using indexed files are that the user does not 
have to compute the maximum size of the file and unusei space on 
the volume is available for other files. In most cases, the user 
should choose an indexed file. © 


5.3.2 Contiguous Files 


The contiguous file is a fixed length file. All bloztks of a 
contiguous file are contiguously allocated adjacently on the 
volume. The file size, in 256-byte sectors, is specified; and 
all required space is reserved at aliocation time. The system 
considers each sector (block) a record. Random reads and writes 
- can access any record on the file, regardless of which records 
were previously accessed, making it possible to write a 
contiguous file in a random fashion. Random and sequential 
access can be mixed without closing ana reassigning the file. 
Contiguous files are supported on all devices supported by the 
moving head or floppy disk drivers, or by a mass storage media 
(MSM) driver. : 


Contiguous file I/0 is nonbuffered, and transfers of variable 
amounts of data occur directly betwean the task buffer and the 
disk. The user can transfer data in logical records greater or 
smaller than a sector sizee The appropriate sector number must 
be specified to position the file for random ccess. All 
transfers begin on a sector boundary (multiple of 256) and ani 
whenever the number of specified bytes is transferred. Following 
a data transfer, the file’s current sector pointer contains tne 
address of the next consecutive sector. The user should always 
transfer an even number of bytes to a contiguous file. 


The contiguous file supports a pseudo filemark capability that 
gives it some of the characteristics of a magnetic tape device. 
The pseudo filemark is an X‘'1313° at the beginning of a record 
(block). Ensure that data containing an X'1313'° is not 
inadvertently written at the beginning of a record. On a 
contiguous file the forward file and backward file operations 
functicn as they would on a magnetic tape. That is, the file is 
respectively positioned forward or backwari until a filemark 
(X¥'1313") is found. For a backward file operation, th2 current 
record pointer is left pointing to the rezord containing the 
filemark (X'°1313'). For a forward file operation, the current 
record pointer is left pointing to the record following the 
filemark. The write-filemark results in writing X'1313" at the 
beginning of the current record. The rest of the record is left 
in an undefined state. 


The shared write access privileges (SRW, SW0O, ERSW) are permitted 
on contiguous files and allow more than one task to append or 
update a contiguous file concurrently. ASCII binary and image 
operations are all supported on contiguous files. Also Supported 
are test and set, wait, unconditional and conditional proceed, 
rewind, backspace record, and forward space record operations. 
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The primary advantage of using contiguous files is that all space 
required for the file is fixed when the file is allocated. Since 
the maximum file length cannot be changed,. the user knows how 
much data can be input. This advantage should be weighed against 
the cost of loss of file space on a volume. 


5-4 FILE STORAGE 


Both indexed and contiguous files can be storel as temporary, 
permanent, or spool files. 


5-4.1 Temporary Files 


Temporary files are used for storage of temporary data. The 
TEMPFILE command allocates and assigns temporary files. See the 
Q0S/32 Operator Reference Manual and the OS/32 Multi-TIerminal 
Monitor (MTM) Reference Manual. 


Temporary files are allocated on the default temporary volume 
which is established by the operator VOLUME sommand. Temporary 
files are given a special filename consisting of the ampersand 
character (&) and the date and time of allocation. These files 
exist only as long as they are assigned and are deleted when the 
assignment is closed. 


5462 Permanent Files 

Permanent files are created whenever indexed and contiguous files 
are created and the TEMPFILE command is not specified. Permanent 
files are deleted only if explicitly deleted by the oparator or 
user through the DELETE command. Files are allocated on the 
default system or user volume. 

5.4.3 Spool Files 

Spool files are created when a task assigns a pseudo printer 
device. Output is sent to the spool file and queued to a slow 
speed output device. Spool files are given a special file nana 
consisting of the at sign character (a) followei by eight digits 
assigned by the Spooler. 
5.5 BUFFER MANAGEMENT 


O0S/32 supports two buffer management methods: 


e Buffered logical (BL) 


e Unbuffered physical (UP) 
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5.5.1 Buffered Logical (BL) 


Indexed files use the buffered logical (BL) management method. 
This method divides files into logical records. The logical 
record length for any given file is fixed when the file is 
allocated, thus becoming a permanent attribute of the file. It 
would be impossible to write 20-byte records on a file one tine 
and write 80-byte records on the same file later. 


It is possible to read or write less than 42 logical record. 
However, this wastes space because the file is physically divided 
into logical records of the size specifiel when the file was 
allocated. Also, it is not possible to write variable length 
records on a file without wasting spacee In this casa, the 
logical record length specified at allocation time must ba the 
size of the longest record the user will ever write on that file. 
If the user tries to read or write a record that is longer than 
the file logical record length, data is lost on a write operation 
or is not returned on 4a read operation. 


The BL method packs logical records into physical blocks as 
efficiently as possible, allowing logical records to overlay into 
the next ohysical block if necessary. The logical racori size 
can exceed the size of a physical block. The only restriction on 
logical record size is that no logical record tan excead 65,535 
bytes. 


In the BL method the current record is interpreted as a logical 
record and not as the physical block number. All 
logical/physical transformations are handled automatically by the 
BL method. When a block is read or written, the actual data 
transfer takes place between the device and a buffer in system 
spacee This buffer is not accessible to the user program... When 
a task reads or writes a record, data is transferred between the 
task and the system buffer. Physical reads and writes take place 
only when required. All actions of the buffer management method 
are transparent to the uSer. 


5.5.2 Unbuffered Physical (UP) 


The unbuffered physical (UP) management method, used by 
contiguous files, works directly with physical blocks. Data is 
directly transferred from a buffer in the user progran to the 
device, without being moved into a system buffer. For a write 
operation, data is moved from the user program directly to the 
file or device. 


In the JP method, the current record pointer points to the 
current physical block. All data transfers must bdegin on a 
physical block boundary. The length of data to be transferred 
can be less or larger than the length of a physical block, but 
not larger than the total size of the file. With contiguous 
files, the current record pointer can be incremented by more than 
One. 
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An advantage of the UP method of transfer is that the time 
required for moving data between a system buffer and user space 
is eliminated. The primary disadvantage is that space on the 
disk volume is often wasted. 

5.6 FILE ACCESS METHODS 


O0S/32 supports two methods of file access: 


e Random access 
-@® Sequential access 
These access methods can be intermixed without Closing and 
reopening the file. 
The current record pointer is a number from 0 to the number of 
logical records currently in the file, indicating the record to 
be read or written on the next sequential access. Each recori is 
numbered in sequence, starting with O-. The current record 
pointer is adjusted in one of these ways: . 
®@® It is set to 0 by: 
- Rewinding 
~ Backspacing to filemark (except on contiguous files where 
the record pointer is positioned at the record containing 
the previous pseudo filemark) . 
- Assigning (except for write access only) 
® It is set to the number of records in the file (the proper 
position to append new records) by: 
- Assigning for write access only 
- Forwarding to filemark (except on contiguous files where 


the record pointer is positioned after the record 
containing the next pseudo filemark) 


-@ It is decremented by one by a backspace record operation, 
-unless the file is already positioned at its beginning. 

e It is incremented by one as follows: 
- Forward record (unless already at EOF) 


~ Sequential read or write to an indexed file 
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® A random read or write sets the current recori pointer to a 
value one greater than the record read or written. 


e It is incremented by the number of sectors that must be 
accessed to satisfy a sequential read or write request to a 
contiguous file. 


5-6-1 Random Access 


For random access, the user supplies the record number to be 
accessed. If this record is found, the data transfer is 
performed, and the current record pointer is set to point to the 
next sequential record. If the user continues to use ranion 
access, the current record pointer is ignored, since it is 
readjusted on every call. However, the usSer can read or write a 
sequence of records, starting with a known racord number. In 
this case, a single random call followed by a number of 
sequential calls can be used. 


Any record allocated for a contiguous file can be read from or 
written to during random access. When indexed files are randomly 
accessed, only records currently in the file can be upiated. In 
addition, index files must be sequentially expanded. If the 
record number specified is more than one record past the end of 
the file, the call is rejected with EOF status. For example, if 
the file has only five records, a sixth could be added; but 
record number 100 could not be added. 


With contiguous files, there is no restriction on using random 
write or read access. Any record within the file’s allocation 
can he read or written. 


5.6.2 Sequential Access 

When the user accesses the files using the sequential methoi 
file, records are read or written in sequence. The current 
record pointer is automatically adjusted at each access. The 
rewind, forward record, backward record, forward file, and 
backward file operations can reposition a file as described. 

5-7 CHOOSING FILE TYPES 

Follow these guidelines to choose a file type: 

If pseudo filematks are required for magnetic tape emulation, the 
contiguous file structure is required. This can occur when 


magnetic tape-oriented programs are used. 


If the maximum length of the file is completely unknown, only an 
indexed file can be used.. 
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Most applications define files so that a logical guess of each 
data structure's maximum length is generally possible. Assuming 
the disk is not badly fragmented, the contiguous file can be 
considered. If the disk is fragmented, the allocation of a large 
contiguous file might not be possible. Use thea 08/32 Disk Backup 
Utility to compress the disk space and eliminate fragmentation. 


If all or most of the file data is to be sequantially accessed, 
choose the indexed file structure. Long files randomly accessed 
require the contiguous file structure. 


For most applications, choose the indexed file bezausea the 
indexed file can perform random and sequential operations. 
However, the index file uSeS an extra Sector as an iniex block 
for every 62 data blocks. 


Once the indexed file structure is chosen, the physical. block 
size must be selected. Reasons were given for keeping the 
physical block size small. However, a large block size can be 
very helpful in some cases. The main time factors involved in a 
disk access are seek time (for moving-head disks) and rotational 
latency time. Usually these times overshaiow the aztual data 
transfer time. Therefore, transferring two or more sactors 
generally costs little more time than a transfer of only one 
sector. For this reason, the number of disk accesses is the 
critical figure in computing file access time. A larg2 physical 
block size can reduce the number of accesses. Consider the 
performance of the overall systen. If a given task is not 
critical or is running in a single task environment, a large 
physical block size might reduce running time. 


If access speed is paramount and the file size is fixed, use the 
contiguous file structure because the amount of systen overhead 
needed to access contiguous files is less than for any other file 
type. 


It is possible to write programs that use both of these file 
Structures aS well as previously existing file structures from 
other programs. The user can use these programs to test the 
application to determine which possible file structures are most 
efficient. 


The contiguous file is compatible with the indexed file, provided 


that the contiguous file does not use tha pseudo filemark 
capability. 


5-8 FILE AND DEVICE PROTECTION 


Files and devices can be statically and dynamically protected. 
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5.8.1 Static Protection Using Read/Write Keys 


Each file or device has associated with it two protection keys, 
one for read access and one for yrite access. Each key is one 
byte long and has a value from X'00° to X'FF*. If the values of 
the keys are within the range X'O1" to X‘FE’, the file or device 
cannot be assigned for read or write access unless the operator 
or requesting task supplies the matching keys. If a key has a 
value of X’00‘, the file or device is unprotected for that aczass 
modee Any.key supplied by the operator or requesting task is 
accepted as valid. If a key has a value of. X'FF', the file is 
unconditionally protected for that access mode. It cannot be 
assigned for that access mode to any u-task, regardless of the 
key supplied. An unconditionally protected file can be assigned 
to an executive task (e-task). Table 5-2 lists the read/write 
keys used for static protection. 


TABLE 5-2 READ/WRITE KEYS 


ee eee we ee ee ee ee ee ee es ee om ee ee ee ee ee ee ee ek wee ey ee ee oe ol OF OP oP Oe OS ow a an om a ow 


read and write. User must supply 
both keys. 
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l 
| KEY | KEY | MEANING | 
} 00 | 00 | Completely unprotected j 
| | | | 
| FF | FF | Unconditionally protected (used | 
| | | by e-tasks) | 
| | | | 
| 07 | 00 | Unprotected for read, coniition- | 
| | J} ally. Protected for write (user | 
| { | must supply write key = X'07°). | 
| | | 
| FF {| A7 | Unconditionally . protectei for | 
| | f write, conditionally protected | 
| | | for read. User must supply read | 
{ | | key of X°A7". | 
| { | | | 
{ 00 | FF | Unprotected for write, uncondi- | 
| | | tionally protected for read | 
| | | | 
{| 27 [32 | Conditionally protected for both | 
| | 
| | | | 


The file protection keys are defined when the file is allocated. 
The system operator or any task having that file assigned for 
exclusive access can change the protection keys. See Section 
5.8.2. The protection keys are changed via the REPROTECT commani 
or a REPROT macro. The device protection keys are jiefined at 
sysgen time, and only the system operator can change them. 
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58.2 Dynamic Protection Using Access Privileges. 
By assigning exclusive access privileges to a file, other tasks 
are prevented from accessing that file. These privileges remain 


in effect as long as the file is assigned to then. The access 
privileges are: 


® Sharable read only (SRO) 

@ Exclusive read only (ERO) 

e Sharable write only (SWO) 

@ Exclusive write only (EWO) 

e Sharable read/write (SRW) 

@ Sharable read, exclusive write (SREW) 

® Exclusive read, sharable write (ERSW) 

® Exclusive read/write (ERW) 

A file cannot be assigned with an access privilege inzompatible 
with an existing assignment of that file. For example, a request 
to open a file for EWO is compatible with an existing assignmant 
of that file for SRO or ERO, but is incompatible with any 
existing assignment for other access privileges. Table 5-3 shows 
which access privileges are compatible. If the user attempts to 
change access privileges by adding aes privilege that is 


incompatible with existing ones, the old access privileges 
remain. 
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TABLE 5-3 ACCESS PRIVILEGE 


COMPATIBILITY 
| } E | | | | | | Ss | | 
| fR{]ETS{t{ StS TEERIE I 
| fs | R{tRI|RIEWT WR] ET R | 
| | Wwi1oyToy;Tuyoyorwa | 
BE SU [ome fee Le tee fe ee 
| | | I | | | | | | 
(ERO: «af eo see a see eee ee ee] 
| | | | [ | | | l | 
ee eae ae a A (cae ee I ae 
{ | ; 4 | | [ ft . | | 
[“Skh: [oe fee. ere Pet = f=] 4 
| | | | | | | | [ | 
EW. Ub ep me ee ape Oe eer a, ee pe 
| | { | | | | | | | 
Re 62 ae et a ce ee ee ce (ae (a 
| | | | | { | | { 
[P<SREW (fos dope fp se ee ee hae fh tee “| 
| | | | | | | | | 
ie, MM a MO ec Rn) ee GR | 

LEGEND 


* Compatible 
- Incompatible 


Exclusive access was discussed in terms of multiple tasks sharing 
the sane file, assuming that a single task does not attempt to 
assign the same file to multiple logical units. However, 
occasionally the same file is assigned to multiple logical units 
as a result of default assignments or system operator 
assignments. In this case, access privileges to the file must be 
assigned to the lu as if it were a task. For example, a file 
cannot be assigned for exclusive read access on one lu and shared 
read on another. If a file is assigned for exclusive reai or 
write access on any given lu, it cannot be assigned for that 
access on any other lu. 


5.8.3 Write-Protected Volumes 


Mark the disk online as a protected device to protect all files 
on a disk from write operations. When a volume is 
write-protected, only assignments for SRO and SRW are accepted; 
SRR is changed ta SRO. If the hardware write-protectad feature 
of a disk is enabled, the volume must be markei on as a protected 
volume. Refer to the 0S/32 Operator Reference Manual. 
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5.8.4 Static and Dynamic Protection Modification 


The system operator or any task having that file assigned for 
exclusive access can change a file's protection keys. If the 
task file is assigned for exclusive write, the write key can be 
changed; if the task has the file assigned for ERW, it can change 
either or both keys. 


Under the proper conditions, a task can change its file access 
privileges without having to close the file. For example, a task 
having a file assigned for shared read cannot change to exclusive 
read if the file is also assigned for shared read to another task 
(or another 1lu of the same task). The CHANGE ACCESS PRIVILEGES 
(CHAP) macro changes the access privilege. The user cannot 
change from read only or write only to read/write, from reali only 
to write only, or from write only to read only. If the user 
attempts to change access privileges and is unable to get the new 
privileges, the old access privileges remain. 


5.9 FILE MANAGEMENT 


This section discusses the ALLOCATE, ASSIGN, close delete (CLDE), 
‘and checkpoint (CKPOINTI) macros. 


5.9.1 File Allocation 


When a file is allocated, its directory entry is built; if it is 
a contiguous file, space is reserved for it on the disk. A file 
can be allocated from the system console or from a user progran 
via an ALLOCATE macro. Regardless of how a file is allocated, 
the following information must be specified: 


Volume id specifies the volume on which the file 
is to be allocated. It must ba the name 
of an online direct access volume, 

otherwise volume error is returned. 


Filename/fextension gives a name to the newly allocated 
file. There must not be any other file 
of that name and extension on the 
specified volume, otherwise an error 
status message is returned. 


Write key/read key sets up the initial protaction keys for 
the file. If this field is not set, the 
default is an unprotected file. 


Logical record is the field used when allozating 

length indexed files. This sets the tLlogical 
record length for the filee It can be 
any size up to 65,535 bytes: however 
once established, it cannot be changed. 
Specifying zero recori length is illegal 
and will result in an error status. 
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Size is the size of the entire file in 
sectors for a contiguous fila. I[t can 
be any size up to the maximum contiguous 
Space available on that volume at that 
time. If the size requested is too 
large, a message is returned. 


For an indexed file, this size is the 
PhySical hlock size for the file in 
sectors. It can be any size up to a 
maximum set at sysgen time for the 
system (never greater than 255). If 
this parameter is tso large, it san be 
difficult to open the file. 


File type ; Indexed or contiguous. 


5.9.2 File Assignment 


The ASSIGN (ALAS) macro or the ASSIGN command assigns a file to 
an lu. At this point, the desired access privileg2s must be 
specified; the read key must be given if read access is 
requested; the write key must be specified if write access is 
requested. 


When a file is assigned, the system allocates within the system 
space a file control block and buffers. Any buffer space 
required depends on the chosen buffer management method ani the 
physical block size of the file. If the file's physical block 
Size is too great for the remaining system space, the file is not 
opened and a buffer error status is returned. When a buffer 
error occurs, the user program can close another open file 
assignment, freeing some system space and allowing the first file 
assignment to be retried. For this reason, d> not keep files 
open longer than necessSarye The phySical block length of the 
file should also be kept as short as possible unless there are 
other overriding considerations. 


5.9.3 File Deassignment (Close). 


Issuing a CLOSE command closes a file assigned to an Iu. 
Information other than the lu asSSignment need not be specified. 
The system waits for any incomplete write fata transfers to 
terminate, writes out to the volume any partially filled buffers, 
and updates the file directory entry. The lu that the file was 
assigned to is closed. 


5.9-4 File Deletion 
A file can be deleted only if it is not currently assigned to a 


task. When using the DELETE macro or command to delete a file, 
the user must supply the volume name as the jefault volume or 
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supply the volume name along with the filename and extension. 
When the file is deleted, the directory entry is removel ani tha 
deleted file's disk space is made available to other files. 


5.9.5 File Checkpointing 


The checkpoint macro (CKPOINT) performs the buffer clearing and 
directory updating functions of a CLOSE macro or command without 
closing the lu. This operation is a protective operation to 
guard against system failure for very critical files or for files 
running for lengthy periods. 


If the system fails, data appended to a file after the latest 
close or checkpoint operation is lost for certain files and 
buffer management methods because the directory is only updated 
at close or checkpointing time. If the system failura does not 
corrupt the volume directory or the physical media, all data 
appended before the file was closed or checkpointed is guaranteed — 
safe. 
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